CreateContainerConfigError: The container cannot be created because something it references does not exist

CreateContainerConfigError means the kubelet could not build the container's configuration, almost always because a referenced ConfigMap, Secret, or key inside one is missing.

Applies to: All Kubernetes versions

What it means

Before starting a container, the kubelet resolves everything the pod spec references — ConfigMaps, Secrets, environment variables sourced from them, and volume mounts built on them. If any of those cannot be resolved, container creation fails before the image is ever run and the status becomes CreateContainerConfigError. Because the failure happens at configuration time rather than runtime, there are no application logs to read: the container never started. The event message names the missing object, which is usually the entire diagnosis.

Most common causes

• A referenced ConfigMap or Secret does not exist in the pod's namespace.
• The object exists but the specific key named in configMapKeyRef or secretKeyRef does not.
• The object was created in a different namespace — these references are namespace-local.
• A typo in the object or key name, including case differences.
• A deployment applied before the ConfigMap or Secret it depends on, in the same manifest bundle.
• The referenced key exists but is optional handling was not set, so a legitimately absent value is treated as fatal.

How to diagnose it

1. Read the event: kubectl describe pod POD. The message names the missing object, for example configmap "app-config" not found or couldn't find key DATABASE_URL in Secret.
2. Confirm the object exists in the right namespace: kubectl get configmap,secret -n NAMESPACE.
3. Inspect the keys inside it: kubectl describe configmap NAME -n NAMESPACE, or for a secret kubectl get secret NAME -o jsonpath='{.data}' -n NAMESPACE.
4. Compare the exact strings in the pod spec against the object — key names are case-sensitive.

How to fix it

1. Create the missing ConfigMap or Secret in the pod's namespace, or correct the reference to point at the object that exists.
2. Add the missing key, or mark the reference optional with optional: true if the application can genuinely run without it.
3. Order manifest application so dependencies exist before the workload that consumes them.
4. Once the missing object is created, delete the pod so it is recreated — the kubelet does not always retry configuration resolution promptly on its own.

Notes

This is distinct from CreateContainerError, which means the configuration resolved but the runtime failed to create the container — a different problem with different causes.

Related

• CreateContainerError — The runtime failed to create the container

Sources

• Kubernetes documentation — ConfigMaps
• Kubernetes documentation — Secrets
• Kubernetes documentation — Debug Pods