| 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, 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. |
| 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. |