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.
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.
Failed to connect to server: connection refused (HTTP/2)
How to fix "HTTP/2 connection refused" error in Kubernetes
missing request for cpu in container
How to fix "missing request for cpu in container" in Kubernetes HPA
error: invalid configuration
How to fix "error: invalid configuration" in Kubernetes
etcdserver: cluster ID mismatch
How to fix "etcdserver: cluster ID mismatch" in Kubernetes
running with swap on is not supported
How to fix "running with swap on is not supported" in kubeadm