Why Your Kubernetes Pod Keeps Restarting: A Complete Debugging Guide
A pod stuck in CrashLoopBackOff is one of the most common Kubernetes problems and one of the most frustrating to debug if you do not have a structured approach. Kubernetes keeps restarting the pod because it keeps crashing, and the backoff timer grows with each attempt, making it slower and slower to observe the next crash.
This guide walks through a systematic approach to diagnosing the root cause, covering the most common failure modes and the exact commands to investigate each one.
Step 1: Check Pod Status
Start with the basics:
kubectl get pods -n <namespace>
Pay attention to three columns. STATUS shows the current state, with CrashLoopBackOff being the clearest signal of repeated crashes. RESTARTS shows how many times Kubernetes has restarted the container, and a high count tells you this is not a one-time event. AGE tells you how long the pod has been running relative to its restart frequency.
A pod that is 2 hours old with 47 restarts is crashing much more aggressively than one with 3 restarts. The restart count informs how urgently you need to investigate.
Step 2: Describe the Pod
The describe output is often the fastest path to the root cause:
kubectl describe pod <pod-name> -n <namespace>
Look at several sections carefully. The Last State block shows the exit code and reason from the previous container run. Exit code 0 means a clean exit, 1 means an application error, 137 means OOMKilled, and 143 means SIGTERM. Each points to a different category of problem.
The Events section at the bottom of the describe output is particularly valuable. It shows what Kubernetes itself observed, including failed image pulls, volume mount failures, probe failures, and scheduling problems. Read it in full before assuming the problem is in your application code.
Step 3: Read the Previous Container Logs
When a container crashes, the current logs may be nearly empty because the crash happened immediately. The most useful logs are from the previous instance:
kubectl logs <pod-name> -n <namespace> --previous
This is one of the most commonly skipped steps. Developers often look at current logs, see nothing useful, and assume the logs are not available. The previous flag is what you need. The exception or error that caused the crash almost always appears here.
Do not delete or restart the pod before collecting these logs. Deletion removes the previous log data along with the pod, leaving you with no information for the next investigation cycle.
Common Causes and How to Fix Them
CrashLoopBackOff from application errors: Look at the previous logs for stack traces, unhandled exceptions, or fatal error messages. Common causes are missing environment variables that the application expects on startup, database connection failures where the database is not yet reachable, invalid configuration values, or code bugs introduced by a recent deployment. Check the Events section for clues about missing ConfigMaps or Secrets.
OOMKilled: The Last State shows Reason: OOMKilled and exit code 137. The container exceeded its memory limit and was terminated by the kernel. Review your resource limits, examine previous logs for signs of memory growth, and look for large in-memory operations in your application code.
Liveness probe failures: If the describe output shows liveness probe failures in the Events section, Kubernetes is killing the container because it does not respond to health checks within the configured timeout. This can mean the application is genuinely unhealthy, or it can mean the probe is misconfigured with too short a timeout or too aggressive a failure threshold. Check whether the probe endpoint actually exists and responds within the expected time.
Readiness probe failures: Readiness probe failures do not cause restarts, but they prevent traffic from reaching the pod. If the pod shows Running but is not receiving requests, readiness failures are usually the cause. The fix is often increasing the initial delay to give the application time to finish startup before the probe begins checking.
ImagePullBackOff: The pod cannot pull its container image. Common causes are a typo in the image name or tag, a private registry that requires authentication credentials not present in the namespace, or a tag that no longer exists in the registry. Check the Events section for the specific pull error message.
Missing ConfigMaps or Secrets: If the pod references a ConfigMap or Secret that does not exist in the namespace, Kubernetes will fail to start the container. The Events section in the describe output will show a clear error about the missing resource. Verify that all referenced ConfigMaps and Secrets exist with kubectl get configmap and kubectl get secret.
Additional Diagnostic Commands
Check resource usage on the node where the pod is scheduled:
kubectl top pod <pod-name> -n <namespace>
kubectl top node
View cluster-level events filtered to your namespace, sorted by time:
kubectl get events -n <namespace> --sort-by='.lastTimestamp'
Review deployment history if the problem started after a recent rollout:
kubectl rollout history deployment <deployment-name> -n <namespace>
If a recent deployment introduced the problem, rolling back is often the fastest path to restoring service while you investigate:
kubectl rollout undo deployment <deployment-name> -n <namespace>
Conclusion
Pod restarts in Kubernetes almost always have a clear, diagnosable cause. The key is following a consistent sequence: check pod status, describe the pod, read previous container logs, and look at cluster events. Each step narrows the problem space significantly.
The single most common mistake is deleting the pod to force a fresh start before collecting the previous logs. Once the pod is deleted, that diagnostic information is gone. Always collect logs before taking any action that might discard state.
A structured approach to debugging Kubernetes pod failures takes five minutes and reliably finds the root cause. Ad-hoc restarts and configuration changes based on guesswork take much longer and often make the problem harder to understand.