🚨 Kubernetes Error Guide: 'configmap not found' — Restore the Reference

Overview

When a pod references a ConfigMap that does not exist in its namespace, the kubelet cannot assemble the container’s configuration and refuses to start it. The pod is scheduled onto a node, but the container stays in Waiting with the reason CreateContainerConfigError, and the events spell out the missing object: configmap "x" not found. Nothing crashes and nothing loops in the app sense — the container simply never gets created because a required input is absent.

You will see this in the pod status column:

NAME                        READY   STATUS                       RESTARTS   AGE
web-5c7d9f8b6a-p2n4x        0/1     CreateContainerConfigError   0          2m15s

ConfigMaps are namespaced, so a reference resolves only within the pod’s own namespace. The usual causes are: the ConfigMap was never created (or was deleted), it lives in a different namespace than the pod, a key named in a valueFrom.configMapKeyRef does not exist even though the ConfigMap does, or a name typo. Because the pod is already scheduled, the fix is never about capacity — it is about making the referenced ConfigMap (and the specific key) exist where the pod looks for it.

Symptoms

• Pod status is CreateContainerConfigError with READY 0/1; the container never reaches Running.
• RESTARTS stays low or 0 — the container is not crashing, it is failing to be created.
• kubectl describe pod events contain Error: configmap "x" not found or couldn't find key <k> in ConfigMap <ns>/<name>.
• The ConfigMap is missing from kubectl get configmap -n <ns>, or exists in a different namespace.

kubectl get pods -l app=web -n prod

NAME                        READY   STATUS                       RESTARTS   AGE
web-5c7d9f8b6a-p2n4x        0/1     CreateContainerConfigError   0          2m15s

kubectl describe pod web-5c7d9f8b6a-p2n4x -n prod | grep -A4 Events

Events:
  Type     Reason     Age               From      Message
  ----     ------     ----              ----      -------
  Warning  Failed     10s (x8 over 2m)  kubelet   Error: configmap "web-config" not found

Common Root Causes

1. The ConfigMap was never created or was deleted

The pod spec references web-config, but no such ConfigMap exists in the namespace — it was forgotten in the manifest set, or removed during cleanup while a Deployment still points at it.

kubectl get configmap -n prod

NAME               DATA   AGE
kube-root-ca.crt   1      30d

web-config is absent. Apply the manifest that creates it (or recreate it), and the pod’s container is created on the next kubelet retry.

2. The ConfigMap is in the wrong namespace

ConfigMaps do not cross namespaces. If the ConfigMap lives in default but the pod runs in prod, the reference cannot resolve — a common mistake when copying manifests between environments.

kubectl get configmap web-config --all-namespaces

NAMESPACE   NAME         DATA   AGE
default     web-config   3      12d

The ConfigMap exists, just not in prod. Recreate it in the pod’s namespace (ConfigMaps cannot be referenced across namespaces).

3. A referenced key does not exist in the ConfigMap

A valueFrom.configMapKeyRef names both a ConfigMap and a key. If the ConfigMap exists but the key does not (renamed, typo’d), the container still fails to be created.

kubectl describe pod web-5c7d9f8b6a-p2n4x -n prod | grep -A3 Events

  Warning  Failed   12s   kubelet   Error: couldn't find key API_URL in ConfigMap prod/web-config

Add the missing key to the ConfigMap, or fix the key: in the pod’s configMapKeyRef.

4. A name typo in envFrom or a volume source

The reference itself may be misspelled. envFrom.configMapRef.name or a volumes[].configMap.name that does not exactly match the object triggers the same not-found error.

kubectl get pod web-5c7d9f8b6a-p2n4x -n prod \
  -o jsonpath='{range .spec.containers[*].envFrom[*]}{.configMapRef.name}{"\n"}{end}'

web-cofnig

web-cofnig is a typo for web-config. Correct the spelling in the Deployment.

5. A required reference that should have been optional

By default a ConfigMap reference is required — the container will not start without it. If the config is genuinely optional (feature flags that fall back to defaults), the reference should be marked optional: true so its absence does not block the pod.

kubectl get pod web-5c7d9f8b6a-p2n4x -n prod \
  -o jsonpath='{.spec.containers[0].envFrom[0].configMapRef}{"\n"}'

{"name":"feature-flags"}

No "optional":true, so the missing feature-flags ConfigMap blocks startup. Either create it or set optional: true on the reference.

Diagnostic Workflow

Step 1: Confirm the config error

kubectl get pod <POD> -n <NS> -o wide

CreateContainerConfigError (not CrashLoopBackOff) means the container is failing to be created, which points at a missing ConfigMap or Secret.

Step 2: Read the exact message in events

kubectl describe pod <POD> -n <NS>

The Events section names the object precisely: configmap "x" not found or couldn't find key <k> in ConfigMap <ns>/<name>.

Step 3: Check whether the ConfigMap exists in this namespace

kubectl get configmap -n <NS>
kubectl get configmap <NAME> --all-namespaces

The first confirms presence in the pod’s namespace; the second reveals a copy sitting in the wrong namespace.

Step 4: Inspect how the pod references the ConfigMap

kubectl get pod <POD> -n <NS> -o jsonpath='{range .spec.containers[*]}{.envFrom}{.env}{"\n"}{end}'
kubectl get pod <POD> -n <NS> -o jsonpath='{.spec.volumes}{"\n"}'

Look at every envFrom.configMapRef, valueFrom.configMapKeyRef, and volumes[].configMap for the exact name and key.

Step 5: Verify the keys inside the ConfigMap

kubectl get configmap <NAME> -n <NS> -o jsonpath='{.data}{"\n"}'

Confirm every key the pod expects is actually present; a renamed key produces the couldn't find key variant.

Example Root Cause Analysis

A web Deployment is updated and its new pods will not start.

kubectl get pods -l app=web -n prod

NAME                        READY   STATUS                       RESTARTS   AGE
web-5c7d9f8b6a-p2n4x        0/1     CreateContainerConfigError   0          2m15s

The events name the missing object:

kubectl describe pod web-5c7d9f8b6a-p2n4x -n prod | grep -A2 Events

  Warning  Failed   8s   kubelet   Error: configmap "web-config" not found

Checking the namespace shows it is not there, but a cluster-wide lookup finds it elsewhere:

kubectl get configmap web-config --all-namespaces

NAMESPACE   NAME         DATA   AGE
staging     web-config   4      6d

The manifest was promoted from staging, but only the Deployment was applied to prod — the ConfigMap was left behind in staging. Since ConfigMaps cannot be referenced across namespaces, the prod pod has nothing to resolve.

Fix: create the ConfigMap in the pod’s namespace, then let the kubelet retry (no restart needed, but a rollout makes it immediate):

kubectl get configmap web-config -n staging -o yaml \
  | kubectl create -n prod -f - --dry-run=client -o yaml | kubectl apply -f -
kubectl rollout restart deployment web -n prod

The container is created and the pod reaches 1/1 Running.

Prevention Best Practices

• Deploy ConfigMaps and the workloads that reference them together as one manifest set so a promotion never leaves the config behind in another namespace.
• Remember ConfigMaps are namespaced and cannot be shared across namespaces — recreate them per environment rather than pointing at another namespace.
• Mark genuinely optional references optional: true so a missing feature-flag ConfigMap degrades gracefully instead of blocking the whole pod.
• Keep ConfigMap key names and the pod’s configMapKeyRef.key values in sync; a renamed key is as fatal as a missing ConfigMap.
• Validate manifests with the Kubernetes validator before applying to catch name typos in envFrom/configMapRef.
• Use a GitOps flow so the desired ConfigMaps are reconciled into the namespace automatically. See more in Kubernetes & Helm guides.

Quick Command Reference

# Confirm the config error (not a crash)
kubectl get pod <POD> -n <NS> -o wide

# Exact missing object / key in events
kubectl describe pod <POD> -n <NS>

# Does the ConfigMap exist in this namespace? Anywhere?
kubectl get configmap -n <NS>
kubectl get configmap <NAME> --all-namespaces

# How the pod references it
kubectl get pod <POD> -n <NS> -o jsonpath='{range .spec.containers[*]}{.envFrom}{.env}{"\n"}{end}'
kubectl get pod <POD> -n <NS> -o jsonpath='{.spec.volumes}{"\n"}'

# Keys inside the ConfigMap
kubectl get configmap <NAME> -n <NS> -o jsonpath='{.data}{"\n"}'

# Recreate in the correct namespace, then re-roll
kubectl rollout restart deployment <DEPLOY> -n <NS>

Conclusion

A configmap "x" not found / CreateContainerConfigError pod is scheduled but cannot have its container created because a referenced ConfigMap is missing. The usual root causes:

1. The ConfigMap was never created or was deleted while a workload still references it.
2. The ConfigMap exists but in a different namespace — ConfigMaps do not cross namespaces.
3. The ConfigMap exists but a referenced key (configMapKeyRef.key) does not.
4. A name typo in envFrom.configMapRef or a volume source.
5. A required reference that should have been marked optional: true.

Start with kubectl describe pod for the exact object name, then confirm with kubectl get configmap -n <ns> (and --all-namespaces) — those two steps identify almost every case. For quick triage, the free incident assistant can turn a config-error describe dump into the likely fix.