Troubleshooting guide · CreateContainerConfigError

CreateContainerConfigError: a container that references something missing

CreateContainerConfigError means the kubelet could not assemble the container's configuration, so it never started it. Almost always the pod names a ConfigMap, a Secret or a key inside one that does not exist in its namespace. The event says which, and the kubelet retries on its own as soon as it appears.

Updated

Read which reference is missing

The Events name the object or key, in lines like configmap "app-config" not found or couldn't find key DATABASE_URL in Secret:

kubectl describe pod <pod> -n <namespace>

The common causes

  • A ConfigMap or Secret that does not exist in the pod's namespace. They are namespaced: one with the right name in another namespace does not count.
  • A key that is not in it — a typo, or a key renamed on one side and not the other, in env valueFrom, envFrom or a volume's items list.
  • An object created after the pod, by a Helm hook, an operator or an External Secrets sync that has not run yet.
  • runAsNonRoot set on a container whose image runs as root. The kubelet refuses to start it and reports this same error, with a message saying so.

Check what exists

Whether the ConfigMap exists, and which keys it holds:

kubectl describe configmap <name> -n <namespace>

Whether the Secret exists, and its key names with their sizes — describe prints no values:

kubectl describe secret <name> -n <namespace>

Fix it

  • Create the missing object in the pod's namespace, or correct the name or key the pod refers to.
  • If the reference is genuinely optional, mark it so — optional: true on a configMapKeyRef, secretKeyRef, envFrom source or volume — and the container starts without it.
  • For runAsNonRoot, run the image as a non-root user with runAsUser, or use an image built to run as one.
  • No restart is needed once the reference resolves: the kubelet keeps retrying and starts the container by itself.

In PodSteer

What PodSteer does about it.

  • A container that cannot be configured is a finding on the overview, with the advice that usually fixes it: a ConfigMap key or Secret that was renamed or never created.
  • The detail panel lists every environment variable with its resolved value — from a ConfigMap, a Secret or the downward API — so you can see what the container is actually given.
  • Secret values stay masked: a Secret's keys are listed, and a value is revealed only when you ask for that one.
A list of deployments in the storefront namespace with checkout open in a detail panel: three replicas desired, current, ready and available, then the pod template with the nginx image, CPU and memory requests and limits, probes, mounts and six environment variables with their values, including the pod's namespace and version, a currency, and a database password shown masked. A list of deployments in the storefront namespace with checkout open in a detail panel: three replicas desired, current, ready and available, then the pod template with the nginx image, CPU and memory requests and limits, probes, mounts and six environment variables with their values, including the pod's namespace and version, a currency, and a database password shown masked.
The detail panel, in the manifest's order. Environment values are shown as the container sees them, and a password stays masked.
Download PodSteer Cluster assessment

Read next

CrashLoopBackOff

The container starts, exits and is restarted with a growing delay. Find the reason in the previous attempt's logs and its exit code.

ImagePullBackOff

The node cannot fetch the container image. The event message says whether the image is missing, the registry refused, or it could not be reached.

Running but not ready

The containers run, but readiness fails, so no Service sends the pod traffic. Check the probe, then the Service's endpoints.