Diagnosing Kubernetes Pod CrashLoopBackOff — Complete Fixes by Cause

What is CrashLoopBackOff?

CrashLoopBackOff is not an error in itself—it is a state. The container keeps starting, crashing, and restarting, so kubelet stretches the restart interval (back-off) to stop a restart storm. In plain terms: the container keeps dying, so kubelet is pausing briefly before trying again.

• Restart interval doubles: 10s → 20s → 40s … up to a maximum of 5 minutes
• The cause lives inside the container, so the real job is finding why it died
• Occurs when restartPolicy is Always (the default) or OnFailure

Step 1: Get the overall picture

kubectl get pods
# NAME        READY   STATUS             RESTARTS   AGE
# myapp-xxx   0/1     CrashLoopBackOff   5          3m

kubectl describe pod myapp-xxx

In the describe output, look at these two places first.

Last State:     Terminated
  Reason:       Error
 Exit Code: 1 ←
Events:
  Warning  BackOff  ...  Back-off restarting failed container

Step 2: Interpret the exit code

The exit code quickly narrows the cause.

Step 3: Check the logs — the most important clue

You need the logs of the previously crashed container, not the current one.

kubectl logs myapp-xxx # (or )
kubectl logs myapp-xxx --previous # when ←
kubectl logs myapp-xxx -c sidecar # when

Fixes by cause

A. Application failed to start (Exit 1)

Usually missing config/env vars, or a failed DB connection.

kubectl logs myapp-xxx --previous
# : "ECONNREFUSED postgres:5432" → DB Service

• Confirm env vars / ConfigMap / Secret are actually injected
• If it's a dependency startup-order problem, wait with initContainers

initContainers:
- name: wait-db
  image: busybox:1.36
  command: ['sh','-c','until nc -z postgres 5432; do echo waiting; sleep 2; done']

B. OOMKilled (Exit 137)

The kernel killed the container because it exceeded its memory limit.

kubectl describe pod myapp-xxx | grep -A3 'Last State'
#   Reason: OOMKilled

Fix: raise the limit, or inspect the app's memory usage.

resources:
  requests: { memory: 256Mi }
 limits: { memory: 512Mi } # +

C. Bad command/args (Exit 127/126)

kubectl logs myapp-xxx --previous
# "exec: \"node\": executable file not found" →

When you override the image ENTRYPOINT, double-check the path and spelling, and drop into a shell for debugging.

kubectl run debug --rm -it --image=myapp:1.0 --command -- /bin/sh

D. Liveness probe failing

The app is fine, but livenessProbe is too aggressive, so kubelet keeps killing it. Exit code is 137/143 and the logs show no error.

livenessProbe:
  httpGet: { path: /healthz, port: 8080 }
 initialDelaySeconds: 30 # boot
  periodSeconds: 10
  failureThreshold: 3
# boot startupProbe
startupProbe:
  httpGet: { path: /healthz, port: 8080 }
  failureThreshold: 30
  periodSeconds: 5

E. Missing config resources (CreateContainerConfigError)

Strictly speaking this is the step before CrashLoop, but you often hit it together.

kubectl describe pod myapp-xxx
# Warning  Failed  ... configmap "app-config" not found

Confirm the referenced ConfigMap / Secret / key exists in the same namespace.

Live debugging techniques

# when — (/)
kubectl get events --sort-by=.lastTimestamp

# when (command sleep )
kubectl run probe --rm -it --image=myapp:1.0 \
  --command -- sleep 3600
kubectl exec -it probe -- sh

# Pod ( without)
kubectl debug -it myapp-xxx --image=busybox:1.36 --target=myapp

Recap

CrashLoopBackOff only means "retrying." The cause is always inside the container. Narrow it down exit code → --previous logs → events and you can systematically fix almost every case.