# Kubernetes pod fails with CreateContainerConfigError

CreateContainerConfigError

Codes: CreateContainerConfigError

Also seen as: configmap not found kubernetes · couldn't find key in ConfigMap · secret not found pod · Error: secret "x" not found

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.

1. 01

   The referenced ConfigMap or Secret does not exist

   primary

   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 "<name>" not found' or 'secret "<name>" not found', and kubectl get on that object returns NotFound

2. 02

   The object exists but the referenced key does not

   common

   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 <key> in ConfigMap <namespace>/<name>'

3. 03

   The object lives in a different namespace

   common

   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. 04

   The pod was created before the object it depends on

   common

   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. 05

   The reference is genuinely optional but not marked as such

   edge

   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

1. 01Read 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 <pod-name> -n <namespace>

2. 02Confirm 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 <name>

3. 03If 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 <name> -n <namespace> -o jsonpath='{.data}' | tr ',' '\n'

4. 04Create whatever is missing in the correct namespace.
   bash

   kubectl create configmap app-config \
     --from-literal=LOG_LEVEL=info \
     -n <namespace>
   

5. 05Where the configuration really is optional, say so explicitly rather than relying on the object always being present.
   yaml

   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. 06Replace 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/<name> -n <namespace>

verify · kubectl get pod shows Running, and kubectl describe pod no longer lists a Failed event mentioning the ConfigMap or Secret.

if that fails · 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.

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

• ✗ 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

1. 01official-docsConfigure a Pod to Use a ConfigMap — Restrictions

   https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/

   The Kubernetes Authors · 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.

   “You must create the ConfigMap object before you reference it in a Pod specification.”

2. 02official-docsSecrets

   https://kubernetes.io/docs/concepts/configuration/secret/

   The Kubernetes Authors · 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.

   “a Secret needs to be created before any Pods that depend on it”

3. 03official-docsDebug Pods

   https://kubernetes.io/docs/tasks/debug/debug-application/debug-pods/

   The Kubernetes Authors · 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.

   “The first step in debugging a Pod is taking a look at it. Check the current state of the Pod and recent events”

highThe 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.

• → Kubernetes pod stuck in CrashLoopBackOff
• → Kubernetes pod stuck in ImagePullBackOff or ErrImagePull