k8s Flashcards: Decision Trainer
Start training
← Back to blog
ConfigMapsSecretsTroubleshootingCKAD

CreateContainerConfigError: Trace the Key Before You Restart

Pod stuck in CreateContainerConfigError? The kubelet cannot build the container config — usually a missing Secret key, wrong subPath, or envFrom reference. Read Events before you delete anything.

2 min read

A deploy lands. The new Pod never reaches Running:

kubectl get pod api-7f2a -n shop
NAME      READY   STATUS                       RESTARTS   AGE
api-7f2a  0/1     CreateContainerConfigError   0          45s

Your instinct might be to restart the Deployment or roll back immediately. Stop there — this status means the kubelet already tried to wire configuration and failed. Deleting the Pod repeats the same error.

Read describe first

kubectl describe pod api-7f2a -n shop

Look at Events near the bottom. Typical messages:

  • couldn't find key DB_PASSWORD in Secret shop/db-creds
  • secret "shop/tls" not found
  • ConfigMap "nginx-conf" not found
  • failed to prepare subPath for volumeMount "config"

The Event names the exact object and key — that is your next move, not a restart.

Common causes

1. Secret or ConfigMap key typo

The volume or envFrom references password but the Secret key is db-password.

kubectl get secret db-creds -n shop -o jsonpath='{.data}' | head

Compare keys to the Pod spec (volumeMounts, env, envFrom).

2. Wrong namespace

The Pod lives in shop but the Secret is in default. Volume mounts cannot reference Secrets in another namespace — copy or sync the Secret, or fix the reference.

3. subPath points at a missing file

ConfigMap mounted with subPath: nginx.conf but the key does not exist or the file was removed from the ConfigMap. The kubelet fails before the container starts.

4. optional: false on envFrom

If a referenced ConfigMap is missing and optional is not set, creation fails hard.

What not to do first

  • Do not delete the Pod hoping the next one succeeds — same spec, same error.
  • Do not assume base64 in the Secret means it is encrypted — encoding is not encryption.
  • Do not patch the Deployment image before confirming the config reference.

Fix order

  1. kubectl describe pod → Events
  2. Verify Secret/ConfigMap exists in the same namespace
  3. Match keys to volume/env references in the Pod template
  4. Fix the manifest or create the missing object
  5. Watch the Pod recover — or only then roll the Deployment if needed

Practice

The Config & Secrets path on Decision Trainer walks these failures with graded first steps — missing keys, cross-namespace mounts, and subPath traps — before you reach for kubectl delete pod.