How to Troubleshoot Kubernetes Pod CrashLoopBackOff Loop
Quick Fix Summary
TL;DRCheck container logs with `kubectl logs -p <pod-name>` to identify the immediate crash reason.
CrashLoopBackOff indicates a pod's container is repeatedly crashing after starting. Kubernetes restarts it with increasing back-off delays between attempts.
Diagnosis & Causes
Recovery Steps
Step 1: Inspect Pod Status and Retrieve Crash Logs
First, get the pod's overall status and then fetch the logs from the previously crashed container instance. The `-p` flag is crucial.
kubectl get pods <pod-name> -o wide
kubectl describe pod <pod-name>
kubectl logs <pod-name> --previousStep 2: Execute Commands in a Debug Container
If logs are insufficient, run an ephemeral debug container inside the pod's context to inspect the filesystem, environment, and test commands.
kubectl debug -it <pod-name> --image=busybox:latest --target=<container-name>
# Once in the shell, inspect:
ls -la /path/to/config
env
cat /proc/1/cmdlineStep 3: Analyze Events and Resource Limits
Check Kubernetes events for scheduling or runtime errors (like OOMKill) and verify the pod's resource requests/limits are appropriate.
kubectl get events --field-selector involvedObject.name=<pod-name>
kubectl top pod <pod-name>
kubectl get pod <pod-name> -o json | jq '.spec.containers[].resources'Step 4: Validate and Test Configuration Independently
Ensure mounted ConfigMaps, Secrets, and environment variables are correctly populated and that the container image runs locally.
kubectl get configmap <configmap-name> -o yaml
kubectl get secret <secret-name> -o yaml
docker run --rm -it --env-file test.env <image-name> <command>Architect's Pro Tip
"For stateful applications, check `kubectl logs --previous` first. For 'ImagePullBackOff', the root cause is often a registry/auth issue, not an app crash."
Frequently Asked Questions
What's the difference between CrashLoopBackOff and ImagePullBackOff?
CrashLoopBackOff means the container started but then crashed. ImagePullBackOff means Kubernetes cannot retrieve the container image from the registry at all.
How long does Kubernetes keep logs from a crashed pod?
By default, logs from terminated containers are retained until the pod is deleted. Using `--previous` accesses logs from the most recent terminated instance.
Can a liveness probe cause a CrashLoopBackOff?
Yes. If a liveness probe fails repeatedly, Kubernetes will restart the container. This manifests as CrashLoopBackOff, but the root cause is the failing probe, not an app crash.