# Configuration and troubleshooting

```json metadata
{
  "schema_version": 2,
  "title": "Configuration and troubleshooting",
  "description": "Review self-managed Redis Agent Memory configuration, troubleshooting guidance, and reference links.",
  "categories": ["docs","operate","iris"],
  "tableOfContents": {"sections":[{"children":[{"id":"external-secret-managers","title":"External secret managers"}],"id":"configuration-reference","title":"Configuration reference"},{"id":"troubleshooting","title":"Troubleshooting"},{"id":"references","title":"References"}]}

,
  "codeExamples": []
}
```


## 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](https://redis.io/docs/latest/operate/iris/agent-memory/self-managed/deploy#3-create-ram-valuesyaml). |
| `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](https://redis.io/docs/latest/operate/iris/agent-memory/self-managed/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](https://redis.io/docs/latest/operate/iris/agent-memory/self-managed/deploy#cl-1). |
| Worker pods `CrashLoopBackOff`; log: `strategies.instruct.llm is required` | The `instruct.llm` block is missing | See [CL-2](https://redis.io/docs/latest/operate/iris/agent-memory/self-managed/deploy#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](https://redis.io/docs/latest/operate/iris/agent-memory/self-managed/deploy#cl-3). |
| Worker callback cannot resolve the Data Plane host | `memory.dataplane_client.base_url` is wrong | See [CL-4](https://redis.io/docs/latest/operate/iris/agent-memory/self-managed/deploy#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](https://redis.io/docs/latest/operate/iris/agent-memory/self-managed/deploy#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](https://redis.io/docs/latest/operate/iris/agent-memory/self-managed/deploy#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](https://redis.io/docs/latest/operate/iris/agent-memory/self-managed/configuration#bring-your-own-byo-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](https://redis.io/docs/latest/develop/ai/context-engine/agent-memory/api-reference) |
| Control Plane API reference | [Control Plane API reference](https://redis.io/docs/latest/operate/iris/agent-memory/self-managed/control-plane-api-reference) |
| Redis Agent Memory Data Plane image tags | [Docker Hub: redislabs/agent-memory](https://hub.docker.com/r/redislabs/agent-memory/tags) |
| Redis Agent Memory Control Plane image tags | [Docker Hub: redislabs/agent-memory-control-plane](https://hub.docker.com/r/redislabs/agent-memory-control-plane/tags) |
| Identity Service image tags | [Docker Hub: redislabs/iris-identity-service](https://hub.docker.com/r/redislabs/iris-identity-service/tags) |