A pod stuck in CrashLoopBackOff or repeatedly failing is one of the most common Kubernetes troubleshooting scenarios — this guide covers a systematic approach to diagnosing and resolving pod failures.
Step 1 — Check Pod Status
kubectl get podsIdentify the specific failure state: CrashLoopBackOff (container starts then crashes repeatedly), ImagePullBackOff (can't pull the container image), Pending (can't be scheduled), or Error — each points toward a different category of root cause.
Step 2 — Check Pod Events
kubectl describe pod POD_NAMEThe Events section at the bottom often reveals the immediate cause — scheduling failures, image pull errors, or resource constraint issues typically show clear, specific messages here.
Step 3 — Check Container Logs
kubectl logs POD_NAMEFor a crashing application, logs from the most recent attempt often show the actual application-level error causing the crash.
Step 4 — Check Logs from the Previous Crashed Instance
kubectl logs POD_NAME --previousIf the pod has already restarted, the current logs may be empty/minimal — --previous retrieves logs from the prior crashed instance, often containing the actual error that caused the crash.
Step 5 — Check Resource Limits
kubectl describe pod POD_NAME | grep -A 5 LimitsSee Kubernetes Resource Requests and Limits Explained — a container hitting its memory limit gets OOMKilled; check the pod's termination reason for "OOMKilled" specifically if crashes correlate with memory-intensive operations.
Step 6 — Check Liveness/Readiness Probe Configuration
See How to Set Up Liveness and Readiness Probes in Kubernetes — an overly aggressive liveness probe (too short a timeout, too strict a success criteria) can cause Kubernetes to kill a genuinely healthy but slow-starting container repeatedly, manifesting as apparent crashes.
Step 7 — Exec Into the Container for Live Debugging
kubectl exec -it POD_NAME -- /bin/shIf the container stays running long enough to exec into, direct investigation from inside can reveal issues not obvious from logs alone — not possible if the container crashes too quickly, in which case consider a debug/sleep override temporarily.
Step 8 — Check ConfigMap/Secret Mounting Issues
See Kubernetes ConfigMaps and Secrets: Managing Configuration Safely — a missing or misconfigured ConfigMap/Secret reference is a common cause of application startup failure; verify referenced configuration resources actually exist and are correctly named.
Step 9 — Check for Image-Related Issues
kubectl describe pod POD_NAME | grep -i imageVerify the image tag exists and is accessible — a typo in the image name/tag, or missing registry credentials for a private image, are common straightforward causes.
Step 10 — Check Node-Level Issues
kubectl describe node NODE_NAMEIf pods are failing to schedule at all (rather than crashing after starting), check node resource availability and any node-level conditions/taints that might be preventing scheduling.
Common Errors
Logs show nothing useful, container exits almost immediately — try overriding the container's command temporarily (command: ["sleep", "3600"]) to keep it running long enough to exec in and investigate manually, then revert once you've diagnosed the issue.
Continue Reading
- How to Set Up Liveness and Readiness Probes in Kubernetes
- Kubernetes Resource Requests and Limits Explained
- Kubernetes ConfigMaps and Secrets: Managing Configuration Safely
Browse more articles in Kubernetes & Container Orchestration.
