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

KubernetesBEGINNERHIGHUpdated Dec 6, 2025· 120 views

A pod references a ConfigMap via configMapKeyRef that doesn't exist, is in a different namespace, or has an incorrect key. Fix by creating the ConfigMap in the correct namespace, verifying key names match exactly, or marking the reference as optional.

Quick fix

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

kubectl get configmap -n <pod-namespace>
kubectl describe configmap <configmap-name> -n <pod-namespace>
  1. Verify ConfigMap exists in pod's namespace
  2. Check pod spec for configMapKeyRef
  3. Create the missing ConfigMap
  4. Verify ConfigMap keys match pod references
kubernetes — error
kubectl get configmap -n <pod-namespace>
kubectl describe configmap <configmap-name> -n <pod-namespace>
couldn't find key "database_host" in ConfigMap app/app-config

What this error means

When a pod uses valueFrom.configMapKeyRef to inject ConfigMap data as an environment variable, Kubernetes resolves the ConfigMap and key at pod startup. If the ConfigMap doesn't exist, is in a different namespace, or lacks the specified key, the pod cannot start. ConfigMaps are namespace-scoped with no cross-namespace access. The error blocks pod startup unless the reference is marked as optional. This prevents the container from running at all, not just failing to receive the environment variable.

Typical symptoms

  • Pod fails to start with CreateContainerConfigError
  • kubectl describe pod shows "couldn't find key [key] in ConfigMap"
  • Pod remains in Pending state indefinitely
  • Expected environment variables missing when container runs
  • Multiple restart attempts with consistent failures
  • Some environment variables appear (for existing keys), others don't

Common causes

  1. ConfigMap does not exist in the pod's namespace
  2. ConfigMap exists in different namespace (no cross-namespace access)
  3. ConfigMap name doesn't match exactly (case-sensitive)
  4. ConfigMap key doesn't exist (case-sensitive)
  5. ConfigMap was deleted or modified after pod deployment
  6. ConfigMap created from file with wrong structure
  7. Deployment ordering: pod starts before ConfigMap is created

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

1Verify ConfigMap exists in pod's namespace

List all ConfigMaps:

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

If missing, create it before deploying the pod.

2Check pod spec for configMapKeyRef

Examine the reference:

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

Expected format:

yaml
env:
- name: DB_HOST
  valueFrom:
    configMapKeyRef:
      name: app-config
      key: database_host
3Create the missing ConfigMap

Using kubectl:

bash
kubectl create configmap app-config \
  --from-literal=database_host=localhost \
  --from-literal=database_port=5432 \
  -n <pod-namespace>

Or YAML:

yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
  namespace: production
data:
  database_host: localhost
  database_port: "5432"
4Verify ConfigMap keys match pod references

Keys are case-sensitive. Check exact names:

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

Update pod spec if key names don't match.

5Mark reference as optional if not critical

Allow pod to start without ConfigMap:

yaml
env:
- name: OPTIONAL_CONFIG
  valueFrom:
    configMapKeyRef:
      name: app-config
      key: optional-setting
      optional: true

Advanced notes

ConfigMap references are blocking by default—pods won't start until ConfigMap is available. Use optional: true for non-critical configs. ConfigMaps have 1 MiB size limit; use external configuration management for larger configs. Updates take ~1 minute to propagate to pods; pod doesn't automatically reload config. For bulk ConfigMap imports, use envFrom.configMapRef; note that keys with hyphens or other invalid characters are silently skipped. Invalid variable names (with hyphens) won't be injected as environment variables even if present in ConfigMap. Use envFrom with optional: true to load all ConfigMap keys safely.

Frequently asked questions

What does "couldn't find key "database_host" in ConfigMap app/app-config" mean?
configMapKeyRef to inject ConfigMap data as an environment variable, Kubernetes resolves the ConfigMap and key at pod startup. If the ConfigMap doesn't exist, is in a different namespace, or lacks the specified key, the pod cannot start. ConfigMaps are namespace-scoped with no cross-namespace access.
How do I fix "couldn't find key "database_host" in ConfigMap app/app-config"?
A pod references a ConfigMap via configMapKeyRef that doesn't exist, is in a different namespace, or has an incorrect key. Fix by creating the ConfigMap in the correct namespace, verifying key names match exactly, or marking the reference as optional.
What causes "couldn't find key "database_host" in ConfigMap app/app-config"?
ConfigMap does not exist in the pod's namespace ConfigMap exists in different namespace (no cross-namespace access) ConfigMap name doesn't match exactly (case-sensitive)
Is the "couldn't find key "database_host" in ConfigMap app/app-config" 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