Configuration and troubleshooting

Review self-managed Redis Agent Memory configuration, troubleshooting guidance, and reference links.

Configuration reference

Use these files to configure a self-managed deployment:

File Purpose
ram-values.yaml Memory configuration and its connection to Identity Service. See step 3.
values-ids.yaml Separate Identity Service release configuration, including runtime credential registration, tenant, and Memory grant validation.
overlay.yaml Redis addresses and provider credentials. The Data Plane, the workers, and the Control Plane all mount it.
ids-metadata.yaml Tells the Identity Service where Metadata Redis is.
license Redis Agent Memory license file provided by Redis.

External secret managers

If you use an external secret manager, expose the license, config, admin-token, Identity Service metadata, Identity Service control token, Data Plane service credential, and Control Plane internal token material as Kubernetes Secrets. Set existingSecret on the owning release. Shared credentials must have matching contents in both releases' namespaces.

Direct CSI file mounts that bypass Kubernetes Secrets are not supported for the Redis Agent Memory license, Data Plane config, Control Plane config, or Control Plane admin-token paths.

For Secrets Store CSI Driver, use sync-to-Kubernetes-Secret (SecretProviderClass.secretObjects). If the Control Plane consumes CSI-synced Secrets, make sure a Control Plane pod also mounts the corresponding SecretProviderClass volume so the synced Secret exists while the pod runs.

Troubleshooting

Symptom Likely cause Fix
helm search repo redis-ai/redis-agent-memory --versions returns no results Helm repo not added/updated, or the chart version has not been published to the repo yet Run helm repo add, helm repo update, or install from the chart package provided by Redis.
Rendering fails because identityService has an additional property Memory values still use the removed bundled contract, such as identityService.enabled or identityService.runtime Move service configuration to values-ids.yaml. Memory accepts only identityService.credential and identityService.allowInsecureTransport; remove externalIdentityService too.
Rendering fails at /externalIdentityService with 'not' failed Values contain the removed external-mode block Remove externalIdentityService and use dataplane.identityServiceBaseURL plus identityService.credential for the standalone connection.
Rendering fails with requires dataplane.identityServiceBaseURL Agent-key authentication or an identity_service subject needs the standalone runtime endpoint Set dataplane.identityServiceBaseURL and identityService.credential.existingSecret. See Deploy.
Rendering fails with requires identityService.credential.existingSecret The endpoint is configured but the runtime credential Secret is missing Name the existing Secret also registered on Identity Service as memory-dp.
Rendering fails with must be https:// or identityService.allowInsecureTransport=true is refused under the fips security profile The runtime endpoint uses HTTP without an allowed exception, or insecure transport is enabled under FIPS Use an HTTPS endpoint. An HTTP exception requires identityService.allowInsecureTransport: true and is refused under FIPS.
Rendering fails with is chart-owned for an introspection field An endpoint, credential, or transport flag was hand-set under memory.auth or shared.auth Use dataplane.identityServiceBaseURL and identityService.credential for chart-rendered configuration; cache settings remain configurable.
Rendering or startup refuses auth.method: none Authentication is disabled outside the development profile Use agent-key authentication. For isolated development only, set both memory.profile: dev and memory.auth.method: none; supplied configuration files use profile: dev and auth.method: none.
Docker pull fails for the configured image tag Image tag is wrong or has not been published to the configured registry Use the image tag listed for the release on Docker Hub or provided by Redis.
Server and worker pods CrashLoopBackOff; log: license validation failed; refusing to start: invalid license format memory.license.license_path is not set See CL-1.
Worker pods CrashLoopBackOff; log: strategies.instruct.llm is required The instruct.llm block is missing See CL-2.
Pods CrashLoopBackOff; log: provider "<name>" is not defined in inference_providers An llm.provider doesn't name an inference_providers entry See CL-3.
Worker callback cannot resolve the Data Plane host memory.dataplane_client.base_url is wrong See CL-4.
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 image.repository, image.tag, registry reachability, and imagePullSecrets; use the Redis Agent Memory release image tag. Configure Identity Service's image and pull Secrets on its own release. See CL-5.
Worker callbacks rejected with 401 auth.worker_identity doesn't match the worker, or the Data Plane cannot fetch the cluster JWKS See CL-6.
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.
Pods are pending during install or upgrade CPU/memory capacity is insufficient for default replicas and rollout overlap Add nodes/headroom or lower replicas for test deployments.
Data Plane health fails Pod not ready, config invalid, Redis unavailable, or license invalid Check pod logs and call /health/liveness and /health/readiness.
Data Plane fails with agent_keys.introspection.base_url is required Bring-your-own (BYO) Data Plane config uses agent-key auth, the default when no auth method is set, without the auth.agent_keys.introspection block Add the auth.agent_keys.introspection block. Only isolated development can use auth.method: none with profile: dev. See Configuration.
Data Plane fails with removed metadata configuration keys: … Config uses metadata keys that version 0.7.0 removed, such as metadata.source or metadata.live Configure metadata.urls, metadata.namespace, and databases, then create stores through the Control Plane.
Pod fails to start in FIPS posture A Redis URL is not rediss://, an outbound HTTP client uses skip_verify: true, an authentication block sets allow_insecure_transport: true, or the Identity Service logs product_validation.<product>.base_url must be an https URL in FIPS profile Update Redis URLs, HTTP client config, authentication blocks, and the Identity Service product validator URL to satisfy the posture checks. The error names the exact config path.
Agent receives 401 Key is missing, revoked, expired, or wrong Check Authorization / X-Api-Key and key status.
Agent receives 503 Identity Service is unreachable, or the Data Plane's miss budget for rejected keys is exhausted Check that the Identity Service pod is Ready and reachable from the Data Plane.
Agent receives 403 Key exists but lacks the required store grant or action Update grants with PATCH http://localhost:9200/v1/api-keys/{keyId} and the Identity Service control token.
Store created by the Control Plane is not visible to the Data Plane Control Plane and Data Plane point at different Metadata Redis URLs or namespaces Make metadata.urls / metadata.namespace match on the Control Plane and the Data Plane.
Agent key is rejected by the Data Plane Data Plane cannot reach the Identity Service, the key was rotated or revoked, or the key secret is wrong Check Identity Service reachability and, with BYO configuration only, auth.agent_keys.introspection. After a rotate or revoke, pods can disagree for up to 5 minutes. Send the latest credential returned by mint or rotate.
Minting an agent key returns 400 for a grant Unknown store ID, mismatched tenant, missing product: "memory", or invalid grant shape Create the store first, match tenantId with Identity Service's runtime.apiKeyTenant.singleTenantID, and verify its productValidation.products.memory endpoint and internal-token Secret match Memory. With BYO Control Plane config, also set auth.internal_token.token_file: /etc/controlplane-onprem/internal/token. Use product: "memory", resourceType: "mem-store", and actions: ["read"], ["write"], or both.
Worker jobs fail after agent-key auth is enabled Worker callback request has no accepted credential, the projected token is not mounted, or auth.worker_identity does not trust the worker subject/audience/issuer Enable workerAuth, set dataplane_client.auth.type=service_account_token, and configure auth.worker_identity.subjects with the worker ServiceAccount subject and required store grants.
Gateway path succeeds but direct external path also works Data Plane is reachable outside the intended gateway path Add NetworkPolicy, ingress, service mesh, or load balancer controls.
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 values values.yaml at the chart root (helm pull redis-ai/redis-agent-memory --version 0.8.0 --untar)
Identity Service chart values helm show values redis-ai/iris-identity-service --version 0.10.0
FIPS values overlay values-fips.yaml at the chart root
NetworkPolicy reference networkpolicy.reference.yaml at the chart root
Chart README README.md at the chart root
Redis Agent Memory API reference Redis Agent Memory API
Control Plane API reference Control Plane API reference
Redis Agent Memory Data Plane image tags Docker Hub: redislabs/agent-memory
Redis Agent Memory Control Plane image tags Docker Hub: redislabs/agent-memory-control-plane
Identity Service image tags Docker Hub: redislabs/iris-identity-service
RATE THIS PAGE
Back to top ↑