{
  "schema_version": 2,
  "id": "operate/iris/intent-router/self-managed/reference",
  "title": "Configuration and troubleshooting",
  "url": "https://redis.io/docs/latest/operate/iris/intent-router/self-managed/reference/",
  "summary": "Look up Helm values and resolve common Intent Router deployment problems.",
  "tags": [
    "docs",
    "operate",
    "iris"
  ],
  "last_updated": "2026-11-02T07:32:08-05:00",
  "page_type": "content",
  "content_hash": "89ccfd96d6979f40de5fd4b54d37d40915cc241740021848f48c0bc02b493d5b",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "This page is a lookup reference for self-managed Intent Router. It lists the main Helm values with their defaults, and a troubleshooting table that matches common symptoms to their causes and fixes. For how to choose and set these values, see [Configuration](https://redis.io/docs/latest/operate/iris/intent-router/self-managed/configuration)."
    },
    {
      "id": "configuration-reference",
      "title": "Configuration reference",
      "role": "configuration",
      "text": "| Value | Default | Meaning |\n| --- | --- | --- |\n| `tenantId` | None | The one tenant the installation serves. Required. |\n| `security.profile` | `\"\"` | Set `fips` for the Federal Information Processing Standards (FIPS) runtime. |\n| `storage.existingSecret` | None | The Secret with the Redis overlays. Required. |\n| `storage.keyPrefix` | `iris:intent` | The Redis key prefix both planes derive their keys from. |\n| `storage.maxRoutersPerTenant` | `128` | Routers the tenant can hold. |\n| `controlplane.reconcile.provisioningDeadline` | `10m` | How long a Router can stay `PROVISIONING` before it fails. |\n| `license.existingSecret` | None | The Secret with the license. Required. |\n| `inference.models` | None | The deployment's embedding model. Required. |\n| `inference.existingSecret` | None | The Secret with `embedders_connection_details` under the key `inference.yaml`. |\n| `inference.allowLocalModels` | `false` | Allow the development-only `noop` provider. |\n| `controlplane.requireDatabase` | `false` | Require every Router to name a customer database. |\n| `controlplane.image.tag`, `dataplane.image.tag` | None | The image tags. Required. |\n| `dataplane.identityServiceBaseURL` | None | The URL of your Identity Service release. Required. Must be `https://` unless `identityService.allowInsecureTransport` is `true`. |\n| `identityService.allowInsecureTransport` | `false` | Accept an `http://` Identity Service URL. Refused in the FIPS profile. |\n| `identityService.credential.existingSecret` | None | The Secret with the data plane's runtime credential, under the key `token`. Required. |\n| `dataplane.startupBudget` | `20s` | How long the data plane's first convergence pass can run. At most `40s`. |\n| `tests.enabled` | `false` | Add `helm test` pods. |\n| `tracing.enabled` | `false` | Send spans to an OpenTelemetry collector. |\n\nSee [Configuration](https://redis.io/docs/latest/operate/iris/intent-router/self-managed/configuration) for the limits and match settings."
    },
    {
      "id": "troubleshooting",
      "title": "Troubleshooting",
      "role": "errors",
      "text": "| Symptom | Likely cause | Fix |\n| --- | --- | --- |\n| `helm install` fails with a named message | A required value is missing, or two tokens share a Secret key. | Set the value named in the message. |\n| A new Router is `FAILED` and `failureReason` mentions vector search | The data-plane Redis has no Search. | Use a Redis 8 build that includes Search, or load the Search and Query engine. |\n| A new Router stays `PROVISIONING` | The data plane can't reach the mailbox, its Redis, or the embedding provider. | Check `runtime.redis.urls` and the data-plane logs. |\n| Data requests return `409` | The Router isn't `READY` yet, or has failed. | Read the Router's state and `failureReason`. |\n| Data requests return `404` for a Router you created | The Router is being deleted, or the ID is wrong. | Read the Router's state from the control plane. |\n| Data requests return `423` | The Router is suspended. | Set the Router's state to `READY`. |\n| Data requests return `503` with `Retry-After` | The Router's index is rebuilding, or its database is unreachable. | Wait for the interval, then check the database. |\n| Data requests return `401` | The key is wrong, expired, or revoked. | Mint or rotate the key. |\n| Data requests return `403` | The key has no grant on the Router, or lacks the action, such as `write`. | Mint a key with the right grant. |\n| Creating a Router returns `409` | The tenant has reached `storage.maxRoutersPerTenant`. | Delete unused Routers or raise the limit. |\n| Updating a Router returns `409` | The Router isn't `READY` or `SUSPENDED`. | Wait for provisioning to finish, or delete a failed Router. |\n| Minting a key fails | `tenantId` differs from the Identity Service's tenant, or the Router doesn't exist. | Set both to the same tenant, and check the Router ID. |\n| Creating a Router fails with `400` | The `vectorSpace` isn't one the deployment offers. | List the models and use one of them. |"
    },
    {
      "id": "references",
      "title": "References",
      "role": "related",
      "text": "- [Data-plane API reference](https://redis.io/docs/latest/develop/ai/context-engine/intent-router/api-reference)\n- [Control-plane API reference](https://redis.io/docs/latest/operate/iris/intent-router/self-managed/control-plane-api-reference)\n- [Service limits and errors](https://redis.io/docs/latest/develop/ai/context-engine/intent-router/limits)"
    }
  ],
  "examples": []
}