KUBERNETES POD FAILS WITH CREATECONTAINERCONFIGERROR ------------------------------------------------------------------------ The image pulled fine, but the kubelet cannot assemble the container's configuration: a referenced ConfigMap or Secret does not exist, or exists without the key the pod asks for. The pod stays in Waiting and no container is ever created. CONFIDENCE : high VERIFIED : 2026-08-07 (fresh, 0d old) URL : https://knowbase.sh/k/kubernetes-createcontainerconfigerror ERROR ------------------------------------------------------------------------ CreateContainerConfigError CODES: CreateContainerConfigError PROBLEM ------------------------------------------------------------------------ A pod sits in Waiting with reason CreateContainerConfigError. The image was pulled successfully, so this is not a registry problem, and there are no logs because no container was ever created. The kubelet retries indefinitely without progressing, because nothing about the pod spec changes on its own. ROOT CAUSE ------------------------------------------------------------------------ 1. [primary] The referenced ConfigMap or Secret does not exist A required reference to an object that was never created, was deleted, or was renamed. Kubernetes refuses to start the container rather than starting it with missing configuration. how to tell: Events read 'configmap "" not found' or 'secret "" not found', and kubectl get on that object returns NotFound 2. [common] The object exists but the referenced key does not configMapKeyRef or secretKeyRef names a key that is absent — often a typo, or a key renamed in the ConfigMap without updating the consumers. how to tell: Events read 'couldn't find key in ConfigMap /' 3. [common] The object lives in a different namespace ConfigMaps and Secrets are namespaced and cannot be referenced across namespaces. A manifest that works in one namespace fails silently in another when the object was only ever created in the first. how to tell: kubectl get configmap -A shows the object present, but under a namespace other than the pod's 4. [common] The pod was created before the object it depends on Applying a manifest directory in the wrong order, or a CI job that creates the Deployment before the ConfigMap. The kubelet keeps retrying, and once the object appears an env-var reference still will not pick it up until the pod is replaced. how to tell: The object now exists and was created after the pod, yet the pod is still failing 5. [edge] The reference is genuinely optional but not marked as such A pod that should tolerate absent configuration will still refuse to start unless the reference carries optional true. how to tell: Adding optional: true to the reference lets the pod start with empty configuration SOLUTION ------------------------------------------------------------------------ 1. Read the pod's events. The kubelet names the exact object and, when the object exists, the exact key it could not find. $ kubectl describe pod -n 2. Confirm whether the object exists in the pod's own namespace. Searching all namespaces at once catches the most common mistake. $ kubectl get configmap,secret -A | grep 3. If the object exists, list its keys and compare them against what the pod asks for. A key that differs by one character fails exactly like a missing object. $ kubectl get configmap -n -o jsonpath='{.data}' | tr ',' '\n' 4. Create whatever is missing in the correct namespace. kubectl create configmap app-config \ --from-literal=LOG_LEVEL=info \ -n 5. Where the configuration really is optional, say so explicitly rather than relying on the object always being present. env: - name: LOG_LEVEL valueFrom: configMapKeyRef: name: app-config key: LOG_LEVEL optional: true note: With optional true and the object absent, the variable is simply unset rather than blocking the container. 6. Replace the pod after fixing the reference. Creating the missing object is not enough on its own for environment-variable references, which are resolved once at container creation. $ kubectl rollout restart deployment/ -n VERIFY: kubectl get pod shows Running, and kubectl describe pod no longer lists a Failed event mentioning the ConfigMap or Secret. FALLBACK: If the object is created by another controller or an external secrets operator that has not reconciled yet, mark the reference optional so the pod can start degraded, and have the application fail its readiness probe until the configuration arrives. APPLIES TO ------------------------------------------------------------------------ Kubernetes: 1.20 and later (CreateContainerConfigError is a Waiting-state reason: the pod phase stays Pending and no container is created.) kubelet: 1.20 and later runtimes: containerd, CRI-O NOT APPLICABLE TO ------------------------------------------------------------------------ - CrashLoopBackOff, where configuration resolved and the container started before exiting - ImagePullBackOff, which fails earlier, at the image pull, before configuration is read - CreateContainerError, which is a container-runtime failure rather than a missing config reference - RBAC errors on the ServiceAccount, which surface as API request failures inside the running application EVIDENCE ------------------------------------------------------------------------ 1. Configure a Pod to Use a ConfigMap — Restrictions https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/ The Kubernetes Authors | official-docs | read 2026-08-07 supports: That a ConfigMap must exist before it is referenced, that an unmarked reference to a missing ConfigMap stops the pod starting, and that a missing key behaves the same way unless the reference is optional. 2. Secrets https://kubernetes.io/docs/concepts/configuration/secret/ The Kubernetes Authors | official-docs | read 2026-08-07 supports: That a Secret must exist before the pods depending on it, and that when the kubelet cannot fetch one it retries and records an Event describing the problem — which is why the pod loops without progressing. 3. Debug Pods https://kubernetes.io/docs/tasks/debug/debug-application/debug-pods/ The Kubernetes Authors | official-docs | read 2026-08-07 supports: That describing the pod and reading its recent events is the first diagnostic step, which is where the missing object and key are named. CONFIDENCE ------------------------------------------------------------------------ high — The creation-order requirement, the optional-reference semantics and the retry behaviour are stated directly in Kubernetes' ConfigMap and Secret documentation. The event strings used as discriminators are the kubelet's own messages rather than quoted documentation, and the namespace-mismatch case follows from ConfigMaps being namespaced rather than from a sentence about this specific failure. ------------------------------------------------------------------------ knowbase 0.1.0 — CC-BY-4.0