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.
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>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
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.
List all ConfigMaps:
kubectl get configmap -n <pod-namespace>
kubectl describe configmap <configmap-name> -n <pod-namespace>If missing, create it before deploying the pod.
Examine the reference:
kubectl get pod <pod-name> -n <pod-namespace> -o yaml | grep -A5 configMapKeyRefExpected format:
env:
- name: DB_HOST
valueFrom:
configMapKeyRef:
name: app-config
key: database_hostUsing kubectl:
kubectl create configmap app-config \
--from-literal=database_host=localhost \
--from-literal=database_port=5432 \
-n <pod-namespace>Or YAML:
apiVersion: v1
kind: ConfigMap
metadata:
name: app-config
namespace: production
data:
database_host: localhost
database_port: "5432"Keys are case-sensitive. Check exact names:
kubectl get configmap app-config -n <pod-namespace> -o jsonpath='{.data}'Update pod spec if key names don't match.
Allow pod to start without ConfigMap:
env:
- name: OPTIONAL_CONFIG
valueFrom:
configMapKeyRef:
name: app-config
key: optional-setting
optional: trueConfigMap 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.