{
  "schema_version": 2,
  "id": "operate/iris/context-gateway/self-managed/reference",
  "title": "Configuration and troubleshooting",
  "url": "https://redis.io/docs/latest/operate/iris/context-gateway/self-managed/reference/",
  "summary": "Review self-managed Context Gateway configuration files, troubleshooting guidance, and reference links.",
  "tags": [
    "docs",
    "operate",
    "iris"
  ],
  "last_updated": "2026-10-30T21:57:11-04:00",
  "page_type": "content",
  "content_hash": "ad33f8858282a059fd00c0621e4d8e90398ad68ef8e3196f9ba0043b7ea473f4",
  "sections": [
    {
      "id": "configuration-reference",
      "title": "Configuration reference",
      "role": "configuration",
      "text": "| File | Purpose |\n| --- | --- |\n| `gateway-values.yaml` | Helm values for both planes. See [step 3](https://redis.io/docs/latest/operate/iris/context-gateway/self-managed/deploy#3-create-gateway-valuesyaml). |\n| `metadata.yaml` | Metadata Redis URLs. Both planes mount it. |\n| `credential-redis.yaml` | Credential Redis URLs, with the encrypted Redis backend. |\n| `config.yaml` | URLs for each registered database. |\n| `license` | Context Gateway license file provided by Redis. |"
    },
    {
      "id": "external-secret-managers",
      "title": "External secret managers",
      "role": "content",
      "text": "Each file reference accepts a Kubernetes Secret or a Secrets Store Container Storage Interface (CSI) Driver file. Scope each CSI class to the files its plane may read, and keep the admin token, internal token, and Vault writer token out of every class the Data Plane mounts."
    },
    {
      "id": "troubleshooting",
      "title": "Troubleshooting",
      "role": "errors",
      "text": "| Symptom | Likely cause | Fix |\n| --- | --- | --- |\n| Control Plane `/health/readiness` answers `503` | The admin or internal token cannot be read or is empty, or the license is not valid. The Data Plane's readiness does not check its token or the license, and an invalid license stops either plane at startup. | Check the admin and internal token Secrets and the license. |\n| Agent receives `401` | Key is missing, revoked, or expired, or sent in the wrong header | Send it as `Authorization: Bearer` or `X-Api-Key`, and check its status. |\n| Agent receives `403` | The key has no `context-gateway` grant for this Gateway | Update the key's grants with the Identity Service control token. |\n| Agent receives `404` | The Gateway does not exist, is being deleted, or belongs to another tenant | Check the Gateway ID and `tenantId`. |\n| Minting an agent key fails for a grant | Unknown Gateway, a tenant mismatch, or the wrong product or resource type | Create the Gateway first. Use `product: \"context-gateway\"` and `resourceType: \"gateway\"`, and match the tenant. |\n| A tool call returns `upstream_credentials_unavailable` | The Data Plane cannot read the Upstream's credential | Check the Data Plane's access to credential storage. |\n| A tool call returns `upstream_rejected_credentials` | The Upstream refused the stored credential | Rotate the Upstream credential. |\n| Cached results keep coming back after a secret rotation | The secret was rotated in place under the same reference | Refresh the Upstream's catalog. |\n| Handles stop being created | The handle memory share or the database-wide 90% guard is reached, the database refused a write, has another eviction policy than `noeviction`, or has no JSON support | Raise `maxmemory`, shorten the handle lifetime, set `noeviction`, or move handles to a dedicated database with JSON. |\n| Large results suddenly come back as stubs | `compression.enabled` was turned on, which applies to every Gateway whose `compression` setting is `ENABLED` | Opt tools out with a `compression` policy of `capture: NEVER`, or set the Gateway's `compression` to `DISABLED`. |\n| Data Plane refuses to start with a default database error | `compression.enabled` is on and the default Gateway database does not use `noeviction` or has no JSON module, or a default names an entry that is not in `databases` | Set `maxmemory-policy noeviction` and load JSON, or fix `defaultDatabases`. See [Default databases](https://redis.io/docs/latest/operate/iris/context-gateway/self-managed/configuration#default-databases). |\n| Turning compression on returns `400` with an `errors[]` entry for `/compression` | The Gateway database does not use `noeviction` or has no JSON module | Fix the database, then repeat the update. A `503` means the database could not be reached. |\n| A new Gateway has `compression` set to `DISABLED` | The create omitted `compression`, and the default Gateway database cannot hold handles or could not be reached | Fix the database, then enable `compression` with an update. |\n| An update or delete returns `412` with `/errors/revision-conflict` | Another change landed after you read the resource | Read it again, then use the new `revision` as `expectedRevision`. |\n| A request returns `413` with `/errors/payload-too-large` | The request exceeds the service size limit | Reduce the request body before retrying. |\n| A Context Surface create returns `400` on `contextSurface.databaseId` | The ID was empty or `null`, or it was omitted and no `defaultDatabases.surfaceDb` is set | Send a registered ID, or set `defaultDatabases.surfaceDb`. |\n| Removing a Gateway's `databaseId` returns `400` | The Gateway's `cache` or `compression` setting is still `ENABLED` | Send both as `DISABLED` in the same update. |\n| A `cache` tool policy returns `400` | The Gateway's `cache` setting is `DISABLED`, or the Gateway has no `databaseId` | Select a database and enable `cache` on the Gateway first. |\n| Agent calls fail authentication | The Data Plane cannot reach `identityService.baseURL` | Check `identityService.baseURL` and the network path. |\n| Context Surface search tools return partial results | Redis is still indexing existing keys after a create, a data model change, or a refresh | Wait until `FT.INFO` on the Surface database shows `percent_indexed` at `1`. |\n| Deleting a Context Surface keeps answering `503` | Its indexes cannot be dropped, often because the Control Plane's Redis user lacks `FT._LIST` or `FT.DROPINDEX` | Grant the commands, or repeat the delete with `ignoreIndexSweepFailure=true`. |\n| A tool policy disappeared | Moving the Upstream to a new endpoint removed policies the new catalog refuses | Read `droppedToolPolicies` in the update response, then set the policies again. |\n| A Context Surface was created without tools | `initialCatalogFailure` in the create response names the cause | Fix the database login or permissions, then refresh the Upstream. |"
    },
    {
      "id": "references",
      "title": "References",
      "role": "related",
      "text": "| Need | Reference |\n| --- | --- |\n| Helm chart values | `values.yaml` in the chart package |\n| Chart examples | `examples/` in the chart package, including Vault, AWS, CSI, and certificate overlays |\n| Chart README | `README.md` in the chart package |"
    }
  ],
  "examples": []
}