Configuration and troubleshooting

Review self-managed LangCache configuration, troubleshooting guidance, and reference links.

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

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, redislabs/iris-langcache-control, redislabs/iris-identity-service
LangCache API reference (Data Plane) LangCache API
Control Plane API reference Control Plane API reference
LangCache overview LangCache overview
License key Contact your Redis representative or contact sales
RATE THIS PAGE
Back to top ↑