{
  "schema_version": 2,
  "id": "operate/iris/langcache/self-managed/reference",
  "title": "Configuration and troubleshooting",
  "url": "https://redis.io/docs/latest/operate/iris/langcache/self-managed/reference/",
  "summary": "Review self-managed LangCache configuration, troubleshooting guidance, and reference links.",
  "tags": [
    "docs",
    "operate",
    "iris"
  ],
  "last_updated": "2026-09-10T15:35:47+03:00",
  "page_type": "content",
  "content_hash": "a7bb97ea3fabb1c11a2e8fc08478266a034c885885c79c642c7a99a4c55d88e7",
  "sections": [
    {
      "id": "configuration-reference",
      "title": "Configuration reference",
      "role": "configuration",
      "text": "Use these files to configure a self-managed deployment:\n\n| File | Purpose |\n| --- | --- |\n| `langcache-values.yaml` | Helm values for images, replicas, services, security posture, Identity Service mode, and non-secret config structure. |\n| `dp-overlay.yaml` | Data Plane's Metadata Redis URLs and (if static) embedding credential, deep-merged over the rendered config at startup. |\n| `cp-overlay.yaml` | Control Plane's Metadata Redis URLs and Cache Redis database registry, deep-merged over the rendered config at startup. |\n| `ids-metadata.yaml` | Bundled Identity Service's own Metadata Redis URLs. |\n| `langcache.key` | LangCache license file provided by Redis. |"
    },
    {
      "id": "external-secret-managers",
      "title": "External secret managers",
      "role": "content",
      "text": "If you use an external secret manager, expose the license, overlay, and\ntoken material to the chart as Kubernetes Secrets and set the chart's\n`existingSecret` values to those Secret names."
    },
    {
      "id": "troubleshooting",
      "title": "Troubleshooting",
      "role": "errors",
      "text": "| Symptom | Likely cause | Fix |\n| --- | --- | --- |\n| Docker pull fails for the configured image tag | Image tag is wrong or not published yet | Use the image tag listed for the release on Docker Hub or provided by Redis. |\n| Pod is stuck in `ImagePullBackOff` or `ErrImagePull` | Cluster cannot pull the configured image, image tag is wrong, registry requires credentials, or `imagePullSecrets` is missing/wrong | Verify `dataplane.image.*`/`controlplane.image.*`/`identityService.bundled.image.*`, registry reachability, and `imagePullSecrets`. |\n| `helm install --atomic --wait` times out and rolls back | Cluster is small or image pull/startup takes longer than Helm's default timeout | Install without `--atomic --wait`, or set a longer `--timeout` and ensure enough cluster capacity. |\n| Chart fails to render with `identityService.mode: bundled` and `security.profile: fips` | The FIPS posture forbids the bundled Identity Service's unencrypted in-cluster address | Use `identityService.mode: external` with a TLS-fronted Identity Service. |\n| Data Plane health fails | Pod not ready, overlay Secret missing/invalid, or Redis unavailable | Check pod logs and call `/health`, `/health/liveness`, and `/health/readiness`. |\n| Cache search or set requests fail with an index error | The RediSearch vector index for the cache was never provisioned, or Cache Redis does not support RediSearch with vector search | Check Control Plane cache status (`GET /v1/caches/{cacheId}`) and Cache Redis modules. |\n| Control Plane `CreateCache` returns `424` | Cache Redis for the resolved `databaseId` is unreachable or does not satisfy LangCache's Redis module requirements | Check the `databases.<id>.urls` connectivity and Redis modules in `cp-overlay.yaml`. |\n| Control Plane `CreateCache` returns `400` | A required field is missing, or a field fails validation — for example `databaseId` doesn't match `^[A-Za-z0-9-]+$`, `defaultSearchThreshold` is outside 0–1, or `attributes` has more than 5 entries | Check the request body against [Control Plane API reference](https://redis.io/docs/latest/operate/iris/langcache/self-managed/control-plane-api-reference). `CreateCache` has no embedding-related fields at all; the embedding provider, model, and dimensions always come from the deployment-wide contract, not the request. |\n| Agent receives `401` | Missing, malformed, revoked, expired, or invalid agent key, or the Data Plane cannot reach the Identity Service | Check the `Authorization` header, key status through the Identity Service, and Data Plane connectivity to the Identity Service (bundled Service or `identityService.external.baseURL`). |\n| Agent receives `403` | Key exists but lacks the required `lc-cache:<cache-id>` grant or action | Update grants through the Identity Service's `/v1/api-keys/{keyId}` endpoint. |\n| Cache created by the Control Plane is not visible to the Data Plane | Data Plane and Control Plane overlays point at different Metadata Redis URLs | Make `dp-overlay.yaml` and `cp-overlay.yaml` use the same `metadata.urls`. |\n| `helm upgrade` doesn't roll a pod after rotating an overlay Secret | The matching `existingSecretChecksum` value wasn't bumped | Recalculate the SHA-256 checksum of the overlay file and set the corresponding `*.existingSecretChecksum` value. |\n| External Identity Service rejects LangCache's introspection calls | The suite-level Identity Service's `product_validation.langcache` isn't configured against this release's Control Plane internal Service and `internalToken` | Ask the Identity Service owner to configure that product entry; see [Authentication and authorization](https://redis.io/docs/latest/operate/iris/langcache/self-managed/authentication#external-identity-service). |\n| NetworkPolicy blocks expected traffic | Placeholder namespace, release name, or caller selectors were not customized correctly | Check the Helm release label `app.kubernetes.io/instance`, caller namespace, and caller pod labels. |"
    },
    {
      "id": "references",
      "title": "References",
      "role": "related",
      "text": "| Need | Reference |\n| --- | --- |\n| Helm chart repository | `https://helm.redis.io/ai`, chart `langcache` |\n| Helm chart values and README | `langcache/helm/` in the LangCache source repository, or the synced copy in `RedisLabs/redis-enterprise-helm` at `ai/charts/langcache` |\n| Container images | Docker Hub: [redislabs/iris-langcache-data](https://hub.docker.com/r/redislabs/iris-langcache-data/tags), [redislabs/iris-langcache-control](https://hub.docker.com/r/redislabs/iris-langcache-control/tags), [redislabs/iris-identity-service](https://hub.docker.com/r/redislabs/iris-identity-service/tags) |\n| LangCache API reference (Data Plane) | [LangCache API](https://redis.io/docs/latest/develop/ai/context-engine/langcache/api-reference) |\n| Control Plane API reference | [Control Plane API reference](https://redis.io/docs/latest/operate/iris/langcache/self-managed/control-plane-api-reference) |\n| LangCache overview | [LangCache overview](https://redis.io/docs/latest/develop/ai/context-engine/langcache) |\n| License key | Contact your Redis representative or [contact sales](https://redis.io/contact/) |"
    }
  ],
  "examples": []
}