{
  "id": "reference",
  "title": "Configuration and troubleshooting",
  "url": "https://redis.io/docs/latest/develop/ai/context-engine/agent-memory/self-managed/reference/",
  "summary": "Review self-managed Redis Agent Memory configuration, troubleshooting guidance, and reference links.",
  "tags": [
    "docs",
    "develop",
    "ai"
  ],
  "last_updated": "2026-07-28T14:23:48-07:00",
  "page_type": "content",
  "content_hash": "ed4919ccbdb9d6143f0ce60e7d5451cc98f185b09b4e908737e322a21935509d",
  "sections": [
    {
      "id": "configuration-reference",
      "title": "Configuration reference",
      "role": "configuration",
      "text": "Use these files to configure a self-managed deployment:\n\n| File | Purpose |\n| --- | --- |\n| `ram-values.yaml` | Helm values for images, replicas, services, Secret names, and optional Control Plane settings. |\n| `memory-dataplane.config.yaml` | Data Plane stores, Redis URLs, auth mode, embedding provider, and worker callback settings. |\n| `controlplane-onprem.config.yaml` | Control Plane metadata Redis, store Redis, admin-token auth, and embedding settings. |\n| `license` | Agent Memory license file provided by Redis. |"
    },
    {
      "id": "external-secret-managers",
      "title": "External secret managers",
      "role": "content",
      "text": "If you use an external secret manager, expose the license, config, and\nadmin-token material to the chart as Kubernetes Secrets and set the chart's\n`existingSecret` values to those Secret names.\n\nDirect CSI file mounts that bypass Kubernetes Secrets are not supported for the\nAgent Memory license, Data Plane config, Control Plane config, or Control Plane\nadmin-token paths.\n\nFor Secrets Store CSI Driver, use sync-to-Kubernetes-Secret\n(`SecretProviderClass.secretObjects`). If the Control Plane consumes\nCSI-synced Secrets, make sure a Control Plane pod also mounts the corresponding\n`SecretProviderClass` volume so the synced Secret exists while the pod runs."
    },
    {
      "id": "troubleshooting",
      "title": "Troubleshooting",
      "role": "errors",
      "text": "| Symptom | Likely cause | Fix |\n| --- | --- | --- |\n| `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. |\n| 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. |\n| 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 Agent Memory release image tag. |\n| `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. |\n| 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. |\n| Data Plane health fails | Pod not ready, config invalid, Redis unavailable, or license invalid | Check pod logs and call `/health`, `/health/liveness`, and `/health/readiness`. |\n| Data Plane fails with `auth.agent_keys.enabled requires metadata.source=live` | Agent-key auth enabled with static stores, for example through `auth.method: agent_key` | Use Control Plane managed stores with `metadata.source: live`, or set `auth.method: none`. |\n| Pod fails to start in FIPS posture | A Redis URL is not `rediss://` or an outbound HTTP client uses `skip_verify: true` | Update Redis URLs and HTTP client config to satisfy the posture checks. |\n| Agent receives `401` | Missing, malformed, revoked, expired, or invalid key | Check `Authorization` / `X-Api-Key`, key status, and metadata Redis connectivity. |\n| Agent receives `403` | Key exists but lacks the required store grant or action | Update grants through `/v1/api-keys/{keyId}`. |\n| Store created by the Control Plane is not visible to the Data Plane | CP and DP point at different Metadata Redis URLs or namespaces | Make CP `metadata.urls` / `metadata.namespace` match DP `metadata.live.urls` / `metadata.live.namespace`. |\n| Agent key minted by the Control Plane is rejected by the Data Plane | Data Plane cannot read the same Metadata Redis records, the key was rotated/revoked, or the key secret is wrong | Check `metadata.source: live`, Metadata Redis connectivity, and send the latest credential returned by mint or rotate. |\n| Minting an agent key returns `400` for a grant | Unknown store ID or invalid grant shape | Create the store first; use `resourceType: \"mem-store\"` and `actions: [\"read\"]`, `[\"write\"]`, or both. |\n| 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. |\n| 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. |\n| 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. |"
    },
    {
      "id": "references",
      "title": "References",
      "role": "related",
      "text": "| Need | Reference |\n| --- | --- |\n| Helm chart values | `deployment/redis-agent-memory/values.yaml` |\n| FIPS values overlay | `deployment/redis-agent-memory/values-fips.yaml` |\n| NetworkPolicy reference | `deployment/redis-agent-memory/networkpolicy.reference.yaml` |\n| Redis Agent Memory API reference | [Redis Agent Memory API](https://redis.io/docs/latest/develop/ai/context-engine/agent-memory/api-reference) |\n| Control Plane API reference | [Control Plane API reference](https://redis.io/docs/latest/develop/ai/context-engine/agent-memory/self-managed/control-plane-api-reference) |\n| Agent Memory Data Plane image tags | [Docker Hub: redislabs/agent-memory](https://hub.docker.com/r/redislabs/agent-memory/tags) |\n| Agent Memory Control Plane image tags | [Docker Hub: redislabs/agent-memory-control-plane](https://hub.docker.com/r/redislabs/agent-memory-control-plane/tags) |"
    }
  ],
  "examples": []
}