highFoundationSymptom-first#configmaps#volumes#configuration#pods

ConfigMap not found — pod can't start, volume mount or env fails

Pod stuck in CreateContainerConfigError or CrashLoopBackOff

Likely source:availabilityconfiguration

Focused incident mode — strips away everything but this runbook.

Symptoms

  • Pod stuck in CreateContainerConfigError or CrashLoopBackOff
  • Events show configmap "<name>" not found
  • Pod fails to start after deploying new ConfigMap-dependent workload

Evidence to grab

Collect these artifacts before you change anything — they prove (or rule out) each cause.

  • Pod events

    kubectl describe pod <pod> -n <namespace> | grep -A5 Events

  • ConfigMap existence

    kubectl get configmap <configmap> -n <namespace>

Diagnostic flow

Run the steps in order, marking each claim confirmed or refuted. The evidence you gather feeds the ranked causes below.

Guided decision tree is ready.

Steps with commands, expected output, and pass/fail branches.

Ranked root causes

Evidence checklist

  • kubectl get configmap returns NotFound
  • Events reference the missing ConfigMap name

Confirm before fixing

kubectl get configmap <configmap> -n <namespace>
READ

Confirm the ConfigMap is absent

Fix

kubectl create configmap <configmap> --from-file=config.yaml -n <namespace>
CHANGE

Create the missing ConfigMap

Expected: configmap/<configmap> created

kubectl rollout restart deployment/<deploy> -n <namespace>
CHANGE

Restart so the pod mounts the ConfigMap

Resolution runbook

Apply from top to bottom after the cause is confirmed. Review every command before running it — risk tags are shown on each.

1
kubectl describe pod <pod> -n <namespace> | grep -A10 Events
READ

Read the error

2
kubectl get configmap <configmap> -n <namespace>
READ

Check existence

3
kubectl create configmap <configmap> --from-file=config.yaml -n <namespace>
CHANGE

Create the missing ConfigMap

4
kubectl rollout restart deployment/<deploy> -n <namespace>
CHANGE

Restart to pick up the ConfigMap

Prevention

  • Create ConfigMaps alongside deployments in Helm charts or Kustomize overlays.
  • Use kubectl dry-run to validate references before apply.
  • Alert on CreateContainerConfigError in the pod status metrics.
  • Version ConfigMap data in Git and apply with the same manifest pipeline as deployments.

Related runbooks

Same stack, same failure family — worth a skim.

MountVolume.SetUp failed — secret not found, pod can't starthigh

Pod stuck in CreateContainerConfigError or CrashLoopBackOff with mount error

KubernetesFoundation3 causes
Open runbook
CrashLoopBackOff — container keeps crashing and restartingcritical

kubectl get pods shows CrashLoopBackOff status

KubernetesFoundation4 causes
Open runbook

Commands marked READ CHANGE DESTRUCTIVE — never run DESTRUCTIVE commands against production data you cannot restore. Copy → verify → execute.