| 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. 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 |
Check the Authorization header and key status through the Identity Service. |
Agent receives 503 |
The Data Plane cannot reach the Identity Service |
Check 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 Data Plane service credential is missing from the external Identity Service's runtime.service_credentials, or lacks api-key-introspect on langcache |
Ask the Identity Service owner to add the credential with that scope; see Authentication and authorization. |
Minting or updating an agent key with a langcache grant fails (external Identity Service) |
The external 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. |
langcache-controlplane restarts and helm install --atomic --wait fails with context deadline exceeded; log: panic: database registry validation failed: database "<id>" ("<name>"): probe store db: ping redis: … |
A Cache Redis in the Control Plane's databases registry is unreachable |
Check each databases.<id>.urls in cp-overlay.yaml. |
| NetworkPolicy blocks expected traffic |
The chart ships no sample policy, and your policy's selectors don't match the LangCache pods or their callers |
Check your policy's selectors, the Helm release label app.kubernetes.io/instance, caller namespace, and caller pod labels. |
helm install --atomic --wait fails with context deadline exceeded; kubectl get events shows Failed to pull image "redislabs/iris-langcache-data:1.0.0": … not found |
An image tag is set that isn't published |
See LC-CL-1. |
curl: (7) Failed to connect to localhost port 9200 after 0 ms: Couldn't connect to server |
The Identity Service isn't port-forwarded |
See LC-CL-2. |
400, "detail":"attributes: no attributes are configured for this cache." |
The request sends an attribute the cache wasn't created with |
See LC-CL-3. |