# Configuration and troubleshooting

```json metadata
{
  "schema_version": 2,
  "title": "Configuration and troubleshooting",
  "description": "Review self-managed LangCache configuration, troubleshooting guidance, and reference links.",
  "categories": ["docs","operate","iris"],
  "tableOfContents": {"sections":[{"children":[{"id":"external-secret-managers","title":"External secret managers"}],"id":"configuration-reference","title":"Configuration reference"},{"id":"troubleshooting","title":"Troubleshooting"},{"id":"references","title":"References"}]}

,
  "codeExamples": []
}
```


## Configuration reference

Use these files to configure a self-managed deployment:

| File | Purpose |
| --- | --- |
| `langcache-values.yaml` | Helm values for images, replicas, services, security posture, Identity Service mode, and non-secret config structure. |
| `dp-overlay.yaml` | Data Plane's Metadata Redis URLs and (if static) embedding credential, deep-merged over the rendered config at startup. |
| `cp-overlay.yaml` | Control Plane's Metadata Redis URLs and Cache Redis database registry, deep-merged over the rendered config at startup. |
| `ids-metadata.yaml` | Bundled Identity Service's own Metadata Redis URLs. |
| `langcache.key` | LangCache license file provided by Redis. |

### External secret managers

If you use an external secret manager, expose the license, overlay, and
token material to the chart as Kubernetes Secrets and set the chart's
`existingSecret` values to those Secret names.

## Troubleshooting

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| 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. |
| 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`. |
| `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. |
| 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. |
| 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`. |
| 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. |
| 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`. |
| 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. |
| 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`). |
| 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. |
| 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`. |
| `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. |
| 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). |
| 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. |

## References

| Need | Reference |
| --- | --- |
| Helm chart repository | `https://helm.redis.io/ai`, chart `langcache` |
| 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` |
| 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) |
| LangCache API reference (Data Plane) | [LangCache API](https://redis.io/docs/latest/develop/ai/context-engine/langcache/api-reference) |
| Control Plane API reference | [Control Plane API reference](https://redis.io/docs/latest/operate/iris/langcache/self-managed/control-plane-api-reference) |
| LangCache overview | [LangCache overview](https://redis.io/docs/latest/develop/ai/context-engine/langcache) |
| License key | Contact your Redis representative or [contact sales](https://redis.io/contact/) |