How to fix couldn't find key "database-password" in Secret default/db-secrets in Kubernetes

KubernetesBEGINNERHIGHUpdated Dec 6, 2025· 148 views

A pod references a Secret via secretKeyRef that doesn't exist, is in a different namespace, or has an incorrect key name. Fix by creating the missing Secret in the correct namespace, verifying key names match exactly (case-sensitive), or marking the reference as optional.

Quick fix

Fixes couldn't find key "database-password" in Secret default/db-secrets

kubectl get secrets -n <pod-namespace>
kubectl describe secret <secret-name> -n <pod-namespace>
  1. Verify the Secret exists in the pod's namespace
  2. Check the pod spec for secretKeyRef
  3. Create the missing Secret
  4. If Secret is in different namespace, copy it
kubernetes — error
kubectl get secrets -n <pod-namespace>
kubectl describe secret <secret-name> -n <pod-namespace>
couldn't find key "database-password" in Secret default/db-secrets

What this error means

When a pod spec uses valueFrom.secretKeyRef to inject Secret data as an environment variable, Kubernetes resolves the Secret name and key at pod startup time. If the Secret doesn't exist, is in a different namespace, or doesn't contain the specified key, the pod cannot start. Secrets are namespace-scoped; there is no cross-namespace access mechanism. The error blocks pod creation entirely unless the reference is marked as optional. This is different from a pod that starts but doesn't receive the environment variable—the pod won't even begin startup.

Typical symptoms

  • Pod fails to start with CreateContainerConfigError
  • kubectl describe pod shows "couldn't find key [key] in Secret [name]"
  • Pod remains in Pending state indefinitely
  • Container logs show secret reference error
  • Environment variable from secretKeyRef is missing in running container
  • Multiple restart attempts with consistent failures
  • kubelet retries Secret resolution if temporarily unavailable

Common causes

  1. Secret does not exist in the cluster
  2. Secret exists in different namespace than pod (namespace isolation)
  3. Secret name in pod spec doesn't match actual Secret name (case-sensitive)
  4. Secret key doesn't exist in Secret data (case-sensitive)
  5. Secret was deleted while pod still references it
  6. Secret created from file without proper key-value structure
  7. Timing race condition: pod starts before Secret is created

How to fix "couldn't find key "database-password" in Secret default/db-secrets"

1Verify the Secret exists in the pod's namespace

Check all Secrets in the namespace:

bash
kubectl get secrets -n <pod-namespace>
kubectl describe secret <secret-name> -n <pod-namespace>

If the Secret doesn't appear, create it before the pod.

2Check the pod spec for secretKeyRef

Examine the environment variable reference:

bash
kubectl get pod <pod-name> -n <pod-namespace> -o yaml | grep -A5 secretKeyRef

Look for:

yaml
env:
- name: DB_PASSWORD
  valueFrom:
    secretKeyRef:
      name: db-secrets
      key: password

Both name and key must match exactly (case-sensitive).

3Create the missing Secret

If the Secret doesn't exist:

bash
kubectl create secret generic db-secrets \
  --from-literal=username=admin \
  --from-literal=password=secret123 \
  -n <pod-namespace>

Or with YAML:

yaml
apiVersion: v1
kind: Secret
metadata:
  name: db-secrets
  namespace: production
type: Opaque
stringData:
  username: admin
  password: secret123
4If Secret is in different namespace, copy it

Secrets cannot be accessed across namespaces:

bash
kubectl get secret <secret-name> -n <source-namespace> -o yaml | \
  sed 's/namespace: <source-namespace>/namespace: <pod-namespace>/' | \
  kubectl apply -f -
5Mark reference as optional if not critical

To allow pod startup without the Secret:

yaml
env:
- name: OPTIONAL_SECRET
  valueFrom:
    secretKeyRef:
      name: db-secrets
      key: password
      optional: true

When optional=true, pod starts even if Secret or key is missing.

Advanced notes

Secrets referenced via secretKeyRef are blocking—pods won't start until the Secret is available. Use optional: true for non-critical secrets to prevent startup failures. Secret updates propagate to pods after ~1 minute (kubelet sync period). For externalized secret management, use External Secrets Operator to pull from Vault, AWS Secrets Manager, or Azure Key Vault. Avoid storing secrets in pod specs or ConfigMaps; use Secrets for sensitive data. Enable encryption at rest in etcd to protect secrets. RBAC should restrict which service accounts can read which secrets.

Frequently asked questions

What does "couldn't find key "database-password" in Secret default/db-secrets" mean?
secretKeyRef to inject Secret data as an environment variable, Kubernetes resolves the Secret name and key at pod startup time. If the Secret doesn't exist, is in a different namespace, or doesn't contain the specified key, the pod cannot start. Secrets are namespace-scoped; there is no cross-namespace access mechanism.
How do I fix "couldn't find key "database-password" in Secret default/db-secrets"?
A pod references a Secret via secretKeyRef that doesn't exist, is in a different namespace, or has an incorrect key name. Fix by creating the missing Secret in the correct namespace, verifying key names match exactly (case-sensitive), or marking the reference as optional.
What causes "couldn't find key "database-password" in Secret default/db-secrets"?
Secret does not exist in the cluster Secret exists in different namespace than pod (namespace isolation) Secret name in pod spec doesn't match actual Secret name (case-sensitive)
Is the "couldn't find key "database-password" in Secret default/db-secrets" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading