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

KubernetesBEGINNERMEDIUMUpdated Dec 6, 2025· 144 views

A pod references a specific key within a Secret that doesn't exist. Secret keys are case-sensitive and must match exactly. Fix by verifying key names in the Secret match pod references, or marking the reference as optional to allow startup.

Quick fix

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

kubectl get secret <secret-name> -n <namespace> -o yaml
  1. Check what keys exist in the Secret
  2. Check pod spec for key references
  3. Fix key name mismatches
  4. Verify key names are case-sensitive
kubernetes — error
kubectl get secret <secret-name> -n <namespace> -o yaml
couldn't find key "database-password" in Secret default/db-secrets

What this error means

When a pod references a Secret, it can either mount the entire Secret as a volume (all keys become files) or reference specific keys for environment variables or volume projections. If the pod tries to access a key that doesn't exist in the Secret's data, Kubernetes cannot satisfy the reference. This is different from a missing Secret itself—the Secret exists, but it doesn't contain the specific key-value pair the pod is requesting. Key names are case-sensitive and must match exactly.

Typical symptoms

  • Pod fails to start with CreateContainerConfigError
  • kubectl describe pod shows "couldn't find key [keyname] in Secret"
  • Pod logs indicate "MountVolume.SetUp failed...references non-existent secret key"
  • Environment variable injected from secretKeyRef is missing or empty
  • Volume mount fails with "volume references non-existent secret key"
  • Pod remains Pending indefinitely waiting for key to appear
  • Some environment variables work (for existing keys) but others are missing

Common causes

  1. Key name in pod spec doesn't match actual key in Secret (case-sensitive)
  2. Secret was created without the expected key-value pairs
  3. Typo in key name in pod manifest (e.g., "password" vs "passwd")
  4. Secret was updated and the key was removed or renamed
  5. Using volume projection with items[] that lists keys not in Secret
  6. Secret created from environment variables missing the expected keys
  7. Multi-environment configs using wrong Secret (dev vs prod)

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

1Check what keys exist in the Secret

Examine the Secret's actual data:

bash
kubectl get secret <secret-name> -n <namespace> -o yaml

The output shows the data section with all key-value pairs. Keys are case-sensitive. Example:

yaml
kind: Secret
metadata:
  name: db-secrets
data:
  username: YWRtaW4=  # base64 for "admin"
  password: c2VjcmV0MTIz  # base64 for "secret123"

This Secret has exactly two keys: username and password. Any other key references will fail.

2Check pod spec for key references

Examine how the pod references Secret keys:

bash
kubectl get pod <pod-name> -n <namespace> -o yaml

Look for:

Environment variable references:

yaml
env:
- name: DB_USER
  valueFrom:
    secretKeyRef:
      name: db-secrets
      key: username  # This key must exist in the Secret

Volume projections:

yaml
volumes:
- name: secrets
  secret:
    secretName: db-secrets
    items:
    - key: username
      path: user.txt
    - key: password
      path: pass.txt

Compare the key values with those shown in step 1. Any mismatch will cause the error.

3Fix key name mismatches

If the key name is wrong in the pod spec, update it to match the Secret:

Option A: Fix the pod manifest

Update the key name to match the Secret:

yaml
env:
- name: DB_PASSWORD
  valueFrom:
    secretKeyRef:
      name: db-secrets
      key: password  # Changed from "passwd" to "password"

Reapply:

bash
kubectl apply -f pod.yaml

Option B: Fix the Secret (if the Secret is wrong)

If the Secret is missing the expected key, add it:

bash
kubectl patch secret db-secrets -p '{"data":{"password":"'$(echo -n "mypassword" | base64)'"}}'  -n <namespace>

Or update via YAML:

bash
kubectl edit secret db-secrets -n <namespace>

Add the missing key in the data section (values must be base64-encoded).

4Verify key names are case-sensitive

Key names are case-sensitive. These are three different keys:
- password
- Password
- PASSWORD

If pod references password but Secret has PASSWORD, it will fail. Double-check capitalization:

bash
kubectl get secret db-secrets -n <namespace> -o jsonpath='{.data}\n'

This shows all keys without base64 encoding, making it easier to verify exact names.

5Recreate Secret with all required keys

If the Secret is missing multiple keys, recreate it:

bash
kubectl delete secret db-secrets -n <namespace>

Then create a new one with all required keys:

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

Or use YAML:

yaml
apiVersion: v1
kind: Secret
metadata:
  name: db-secrets
  namespace: production
type: Opaque
stringData:
  username: admin
  password: secret123
  host: db.example.com

Apply: kubectl apply -f secret.yaml

6Mark the key reference as optional if not critical

If the key is optional (not essential for application startup), mark it as optional:

For environment variables:

yaml
env:
- name: OPTIONAL_KEY
  valueFrom:
    secretKeyRef:
      name: db-secrets
      key: optional-setting
      optional: true  # Pod starts even if key is missing

For volume projections:

yaml
volumes:
- name: secrets
  secret:
    secretName: db-secrets
    items:
    - key: optional-key
      path: optional.txt
      mode: 0644

When optional: true, the pod starts without that environment variable or volume file. The application must handle missing values gracefully.

7Verify pod can now start

After fixing key mismatches, verify the pod starts:

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

Pod status should be Running. Check logs:

bash
kubectl logs <pod-name> -n <namespace>

Verify environment variables were injected correctly:

bash
kubectl exec <pod-name> -n <namespace> -- env | grep -i secret

Or check volume mount:

bash
kubectl exec <pod-name> -n <namespace> -- ls -la /etc/secrets/

Advanced notes

Key names are case-sensitive and whitespace matters—avoid spaces and special characters in key names. When creating Secrets from files with kubectl create --from-file, the filename becomes the key and the file contents become the value; this is useful for certificates and config files. Secret values are base64-encoded (not encrypted) in etcd by default; enable encryption at rest to protect sensitive data. Use stringData field in YAML for plain text values; Kubernetes automatically base64-encodes them. When referencing multiple keys from the same Secret using volume projections, use the items[] field to list only needed keys; unlisted keys won't be mounted. For validation: use kubectl apply --dry-run=client to catch key mismatches before deploying. Secret updates propagate to running pods after ~1 minute (kubelet sync period); for immediate updates, recreate the pod or use a sidecar that watches for changes. If using external secrets (Vault, AWS Secrets Manager), ensure the External Secrets Operator correctly maps remote keys to Kubernetes Secret keys.

Frequently asked questions

What does "couldn't find key "database-password" in Secret default/db-secrets" mean?
When a pod references a Secret, it can either mount the entire Secret as a volume (all keys become files) or reference specific keys for environment variables or volume projections. If the pod tries to access a key that doesn't exist in the Secret's data, Kubernetes cannot satisfy the reference. This is different from a missing Secret itself—the Secret exists, but it doesn't contain the specific key-value pair the pod is requesting.
How do I fix "couldn't find key "database-password" in Secret default/db-secrets"?
A pod references a specific key within a Secret that doesn't exist. Secret keys are case-sensitive and must match exactly. Fix by verifying key names in the Secret match pod references, or marking the reference as optional to allow startup.
What causes "couldn't find key "database-password" in Secret default/db-secrets"?
Key name in pod spec doesn't match actual key in Secret (case-sensitive) Secret was created without the expected key-value pairs Typo in key name in pod manifest (e.g., "password" vs "passwd")
Is the "couldn't find key "database-password" in Secret default/db-secrets" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading