CrashLoopBackOff
This error occurs when a container in a Pod repeatedly starts, crashes, and restarts in an increasing back-off loop.
Usually happens because:
- ☑ Application process crashes during initialization
- ☑ Missing ConfigMaps, Secrets, or configuration environment parameters
- ☑ Docker entrypoint script finishes and exits immediately
🔍 Quick Checklist:
What is CrashLoopBackOff?
A 'CrashLoopBackOff' is a common Kubernetes pod state indicating that a container cannot start or run successfully, leading the kubelet to restart it repeatedly with an exponential delay (back-off). The delay starts at 10 seconds and doubles at each retry up to a maximum of 5 minutes. This state is not the crash itself; rather, it is Kubernetes' mechanism to protect cluster resources from being overwhelmed by a failing container.
Common Causes
- Application code failure: The primary container process crashes or throws uncaught exceptions during startup.
- Missing configuration or environment files: The application relies on variables, config maps, or secrets that have not been populated.
- Misconfigured container commands or ports: The Docker entrypoint command fails, exits immediately, or attempts to bind to blocked ports.
| Cause | Frequency |
|---|---|
| Application process crashes (exit code 1 or unhandled exceptions) | ⭐⭐⭐⭐⭐ |
| Missing referenced ConfigMap, Secret, or config file | ⭐⭐⭐⭐ |
| Misconfigured CMD or ENTRYPOINT command exiting immediately | ⭐⭐⭐ |
Common Mistakes
- Attempting to read active container logs (`kubectl logs pod-name`) instead of historical logs (`kubectl logs pod-name --previous`), showing blank screens if the container is currently in the back-off pause loop.
- Forgetting that exit code 137 indicates the container was forcefully terminated by the OS Out-Of-Memory killer (OOMKilled).
How to Fix
Kubernetes Operations & Verification
Execute diagnostic steps to locate the exact trigger of the CrashLoopBackOff.
# 1. Inspect the Pod status and find restarting containers
kubectl get pods
# 2. View details, looking for Exit Code and Last State events
kubectl describe pod web-deploy
# 3. Pull logs from the container that crashed just before the restart
kubectl logs web-deploy --previousPlatform Specific Fixes
Retrieve exit code statistics from Pod status attributes using jsonpath selectors.
kubectl get pod web-deploy -o jsonpath='{.status.containerStatuses[*].lastState.terminated.exitCode}'Best Practices
- Run Docker containers locally to verify they run in the foreground without crashing before pushing images to registry libraries.
- Utilize liveness and readiness probe delays to prevent premature container terminations during slow application startups.
Frequently Asked Questions (FAQ)
Q: What is CrashLoopBackOff?
It means a container in a Pod is crashing repeatedly, and Kubernetes is waiting an increasing amount of time before trying to restart it again to avoid overloading the system.
Q: How do I view logs for a crashed container?
If the container has already restarted, run 'kubectl logs <pod-name> --previous'. This shows the logs of the container instance that just crashed, rather than the currently restarting one.
Q: What do the exit codes mean in a CrashLoopBackOff?
Common exit codes in 'kubectl describe pod' are: Exit Code 1 (Application crash/general error), Exit Code 137 (OOMKilled - container exceeded memory limits), and Exit Code 0 (Container completed its task and exited because it wasn't a long-running service).
Q: Why does my container exit with Exit Code 0?
If a container is not configured to run as a long-running daemon (like a web server or worker), it runs its script, exits successfully, and Kubernetes restarts it thinking it should keep running. Ensure your entrypoint starts a persistent process.