CreateContainerConfigError

KubernetesKubernetes

Fix CreateContainerConfigError: run kubectl describe pod and read the Events. Usually a missing Secret, ConfigMap, key or ServiceAccount the Pod references.

easy fix·6 min read·4 causes

By Vishvesh Patel·DevOps Engineer·Updated 16 September 2026

Run these in order. Each one tells you what its output means before you change anything.

• Get the exact missing reference

The Events line names it precisely. Secret "payments-db-credentials" not found, or couldn't find key DATABASE_URL in ConfigMap app-config. That string is the entire diagnosis.

• Check whether it exists, and in which namespace

Secrets and ConfigMaps never cross namespaces. If it exists in another one you have to copy it into this namespace. A reference will not reach it.

• If the object exists, the key name is wrong

Compare the keys listed here against the configMapKeyRef or secretKeyRef in the Pod spec. Key names are case-sensitive and a missing key fails the whole container.

If the steps above did not settle it, these are the causes in the order they are usually responsible. Each section explains why it happens and how to confirm it.

CreateContainerConfigError means the kubelet could not assemble the container's configuration. It never tried to start your image, so nothing in your application is responsible.

Something the Pod spec references does not exist, and the cause is almost always one of four things: a missing Secret, a missing ConfigMap, a key that is absent from one that does exist, or a missing service account.

The Error: line names the exact object. That is the whole diagnosis. There is rarely any need to look further.

Three reasons it is absent, in order of frequency.

Wrong namespace. Secrets and ConfigMaps are namespaced, and there is no cross-namespace reference. A Secret in default is invisible to a Pod in payments:

There it is, in the wrong namespace. Copy or recreate it where the Pod runs.

Ordering. The Deployment was applied before the Secret. Kubernetes does not queue and retry indefinitely in a useful way here; it just keeps failing. Apply the Secret and the Pod recovers on its next attempt with no restart needed.

A typo. Compare exactly, since payments-db-credential and payments-db-credentials look identical at a glance:

This is the subtler version, and the one that survives a "the ConfigMap is there" check.

DATABASE_URL versus database_url. Keys are case-sensitive, and this is the most common form of this error. Someone renamed a key, or the manifest and the ConfigMap were written by different people.

That lists a Secret's keys without printing the values, which is what you usually want.

• Make a key optional when it genuinely is

With optional: true the variable is simply unset rather than blocking the Pod. Use it for genuinely optional configuration, and not as a way to silence this error on something the application needs, which converts a clear startup failure into a confusing runtime one.

The same flag works on secretKeyRef, and on whole envFrom entries.

A Deployment referencing a service account that was never created, or that lives in another namespace. Common after copying manifests between environments where the service account is created by a separate chart or Terraform module.

Environment variable names have rules, and a key that is fine in a ConfigMap may be invalid as a variable:

A ConfigMap key containing dots is valid as a key and invalid as an environment variable name. Mount it as a file instead, or rename the key.

Two similar statuses with different meanings, and distinguishing them saves time:

CreateContainerConfigError never runs your image. CrashLoopBackOff means it ran and failed, which is a different investigation entirely.

Several Pods failing on the same object usually means one missing Secret across a namespace: a deleted sealed secret, an External Secrets sync failure, or a Terraform apply that did not complete.

Apply Secrets and ConfigMaps before workloads, or use Helm, which orders them by default with hooks available for anything that needs it.

Use optional: true for configuration that genuinely is.

Validate references in CI. A simple check comparing every configMapKeyRef and secretKeyRef in your manifests against the keys that exist catches this before a deploy rather than during one.

Prefer envFrom with whole objects where you consume most keys, since it removes the per-key name coupling that causes cause 2.

What causes CreateContainerConfigError in Kubernetes?

The kubelet could not assemble the container's configuration, so it never started your image. Four causes account for nearly all of it: a Secret that does not exist, a ConfigMap that does not exist, a key missing from one that does, or a missing service account. kubectl describe pod puts the exact object name in the events Error: line, which is usually the complete diagnosis, no application logs are involved, because the application never ran.

Why does Kubernetes say my Secret is not found when it exists?

Almost always a namespace mismatch. Secrets and ConfigMaps are namespaced and cannot be referenced across namespaces, so a Secret in default is invisible to a Pod in payments. Run kubectl get secret <name> -A to see every namespace at once. Finding it somewhere else is the answer. The other causes are a typo in the reference and the Deployment having been applied before the Secret existed.

What does "couldn't find key X in ConfigMap" mean?

The ConfigMap exists but does not contain that key, and keys are case-sensitive, DATABASE_URL and database_url are different. List what is actually there with kubectl get configmap <name> -o jsonpath='{.data}' and compare exactly. This is the version of the error that survives a quick "the ConfigMap is there" check, and it usually follows a rename or a manifest written against a different environment.

How do I make a ConfigMap or Secret key optional?

Add optional: true alongside configMapKeyRef or secretKeyRef, and the environment variable is simply left unset rather than blocking the Pod. It works on whole envFrom entries too. Use it for configuration that genuinely is optional. Applying it to something the application needs converts an obvious startup failure into a confusing runtime one, which is a considerably worse outcome.

What is the difference between CreateContainerConfigError and CrashLoopBackOff?

CreateContainerConfigError means the container was never created, because its configuration could not be assembled from the referenced Secrets, ConfigMaps and service account. CrashLoopBackOff means the container was created, started, and exited repeatedly, so your image ran and something inside it failed. The first is a manifest or cluster-object problem with no application logs to read; the second needs kubectl logs --previous.

Do I need to restart the Pod after creating the missing Secret?

No. The kubelet keeps retrying container creation with backoff, so creating the missing object lets the Pod proceed on its own within a minute or two. You only need to intervene if the Pod spec itself is wrong, a typo in the reference, or a key name that does not exist, since that requires editing the Deployment, which triggers a new ReplicaSet and new Pods anyway.

Free, comprehensive DevOps tutorials and learning roadmaps. Master Docker, Kubernetes, CI/CD, and more.

Get notified about new tutorials and features.

• Roadmaps

• Interview Prep

• Certifications

• Company

© 2026 DevOpsLesson. All rights reserved.