How to fix couldn't find key "database_host" in ConfigMap app/app-config in Kubernetes

KubernetesBEGINNERMEDIUMUpdated Dec 6, 2025· 135 views

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

Quick fix

Fixes couldn't find key "database_host" in ConfigMap app/app-config

kubectl get configmap app-config -n <namespace> -o yaml
  1. View all keys in the ConfigMap
  2. Check pod spec for key references
  3. Verify exact key name match (case-sensitive)
  4. Update pod spec to match ConfigMap keys
kubernetes — error
kubectl get configmap app-config -n <namespace> -o yaml
couldn't find key "database_host" in ConfigMap app/app-config

What this error means

When a pod references a ConfigMap, it can either mount the entire ConfigMap as a volume (all keys become files) or reference specific keys for environment variables. If the pod references a key that doesn't exist in the ConfigMap's data section, Kubernetes cannot satisfy the reference. This is distinct from a missing ConfigMap itself—the ConfigMap exists, but it doesn't contain the specific key the pod is requesting. ConfigMap key names are case-sensitive and must match exactly, including underscores, hyphens, and dots.

Typical symptoms

  • Pod fails to start with CreateContainerConfigError
  • kubectl describe pod shows "couldn't find key [keyname] in ConfigMap"
  • Pod logs indicate "MountVolume.SetUp failed...references non-existent configmap key"
  • Environment variable injected from configMapKeyRef is missing
  • Volume mount fails with "volume references non-existent configmap key"
  • Pod remains Pending indefinitely
  • Only some environment variables are injected (for existing keys); others are missing

Common causes

  1. Key name in pod spec doesn't match actual key in ConfigMap (case-sensitive)
  2. ConfigMap was created without the expected key-value pairs
  3. Typo in key name in pod manifest (e.g., "database_host" vs "DATABASE_HOST")
  4. ConfigMap was updated and the key was removed or renamed
  5. Using volume projection with items[] containing keys not in ConfigMap
  6. ConfigMap created from file has different key structure than expected
  7. Mixing hyphens and underscores in key names

How to fix "couldn't find key "database_host" in ConfigMap app/app-config"

1View all keys in the ConfigMap

Examine the ConfigMap's actual data:

bash
kubectl get configmap app-config -n <namespace> -o yaml

The output shows all keys in the data section. Example:

yaml
kind: ConfigMap
metadata:
  name: app-config
data:
  DATABASE_HOST: localhost
  DATABASE_PORT: "5432"
  APP_ENV: production

This ConfigMap has exactly three keys: DATABASE_HOST, DATABASE_PORT, and APP_ENV. Any other key references will fail.

Alternatively, use:

bash
kubectl get configmap app-config -n <namespace> -o jsonpath='{.data}'

This displays keys without formatting, making exact names easier to verify.

2Check pod spec for key references

Examine how the pod references ConfigMap keys:

bash
kubectl get pod <pod-name> -n <namespace> -o yaml | grep -A10 configMap

Look for:

Environment variable references:

yaml
env:
- name: DB_HOST
  valueFrom:
    configMapKeyRef:
      name: app-config
      key: DATABASE_HOST  # This key must exist in the ConfigMap

Bulk import (envFrom):

yaml
envFrom:
- configMapRef:
    name: app-config  # All keys imported as env vars (invalid names skipped)

Volume projections:

yaml
volumes:
- name: config
  configMap:
    name: app-config
    items:
    - key: DATABASE_HOST
      path: db-host.conf

Compare all key values with those shown in step 1.

3Verify exact key name match (case-sensitive)

Key names are case-sensitive. These are three different keys:
- database_host
- DATABASE_HOST
- Database_Host

If the ConfigMap has DATABASE_HOST but the pod references database_host, it will fail.

Compare side-by-side:

bash
# Show ConfigMap keys
echo "ConfigMap keys:"
kubectl get configmap app-config -n <namespace> -o jsonpath='{.data}\n' | jq 'keys'

# Show pod references
echo "Pod references:"
kubectl get pod <pod-name> -n <namespace> -o yaml | grep 'key:' | sed 's/.*key: //'

The keys must match exactly, including capitalization and punctuation.

4Update pod spec to match ConfigMap keys

Fix the pod manifest to reference correct key names:

yaml
apiVersion: v1
kind: Pod
metadata:
  name: my-app
spec:
  containers:
  - name: app
    image: my-image
    env:
    - name: DB_HOST
      valueFrom:
        configMapKeyRef:
          name: app-config
          key: DATABASE_HOST  # Match ConfigMap key exactly (case-sensitive)
    - name: DB_PORT
      valueFrom:
        configMapKeyRef:
          name: app-config
          key: DATABASE_PORT  # Not "database_port"
    volumeMounts:
    - name: config
      mountPath: /etc/config
  volumes:
  - name: config
    configMap:
      name: app-config
      items:
      - key: DATABASE_HOST  # Must exist in ConfigMap
        path: db-host.txt

Apply:

bash
kubectl apply -f pod.yaml
5If ConfigMap is missing keys, add them

If the ConfigMap doesn't have required keys, update it:

Using kubectl patch:

bash
kubectl patch configmap app-config -n <namespace> -p '{"data":{"NEW_KEY":"value"}}'

Using kubectl edit:

bash
kubectl edit configmap app-config -n <namespace>

Add keys to the data section (no base64 encoding needed for ConfigMaps).

Using YAML update:

yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
  namespace: production
data:
  DATABASE_HOST: localhost
  DATABASE_PORT: "5432"
  APP_ENV: production
  LOG_LEVEL: debug  # Add missing key

Apply: kubectl apply -f configmap.yaml

6Recreate ConfigMap if key structure is wrong

If ConfigMap was created incorrectly (e.g., from a file with wrong structure):

bash
kubectl delete configmap app-config -n <namespace>

Recreate with correct keys:

bash
kubectl create configmap app-config \
  --from-literal=DATABASE_HOST=localhost \
  --from-literal=DATABASE_PORT=5432 \
  --from-literal=APP_ENV=production \
  -n <namespace>

Verify:

bash
kubectl get configmap app-config -n <namespace> -o yaml
7For envFrom imports, remember invalid var names are skipped

When using envFrom to import all ConfigMap keys as environment variables:

yaml
envFrom:
- configMapRef:
    name: app-config

Kubernetes automatically imports all keys as environment variables. However, if a key name is invalid as an environment variable (contains hyphens, starts with number, etc.), it's silently skipped. Example:

ConfigMap with keys:
- DATABASE_HOST → imported as env var ✓
- database-port → skipped (contains hyphen) ✗
- 2FAST → skipped (starts with digit) ✗

If you need these keys as environment variables, reference them explicitly:

yaml
env:
- name: DB_PORT
  valueFrom:
    configMapKeyRef:
      name: app-config
      key: database-port
8Mark key references as optional if not critical

If the key is optional, mark it as optional to allow pod startup:

yaml
env:
- name: OPTIONAL_SETTING
  valueFrom:
    configMapKeyRef:
      name: app-config
      key: optional-key
      optional: true  # Pod starts even if key is missing

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

Advanced notes

Key names are case-sensitive and whitespace-aware. Avoid spaces, hyphens at the start, or special characters in key names unless necessary. When creating ConfigMaps from files with --from-file, the filename becomes the key and the file contents become the value; useful for complex config (JSON, YAML, INI). ConfigMap data is limited to 1 MiB total; split large configs into multiple ConfigMaps. When using volume mounts with items[], only listed keys are projected as files; unlisted keys are ignored. ConfigMap updates propagate to running pods within ~1 minute (kubelt sync period); pod doesn't automatically reload config—application must handle reloading or pod must be recreated. For immutable configs, mark the ConfigMap as immutable after creation (immutable: true) to prevent accidental changes. When using envFrom, check pod events for skipped keys due to invalid variable names. For validation: use kubectl apply --dry-run=client before deploying to catch key mismatches early.

Frequently asked questions

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

Official resources & further reading