You apply a new deployment manifest or update a container image in your cluster using kubectl apply -f deployment.yaml. You run kubectl get pods to verify that the workload is healthy, only to watch the pod cycle through Running, Error, and finally freeze in a perpetual restart state: CrashLoopBackOff. Each failed restart increases the backoff delay exponentially (10s, 20s, 40s, up to 5 minutes), bringing application availability to a standstill.
The Kubernetes CrashLoopBackOff error is an alert indicating that a container in a pod has repeatedly started, crashed, and been scheduled for restart by the kubelet daemon. Rather than being a failure in Kubernetes itself, CrashLoopBackOff is a protective symptom: the kubelet is intentionally throttling restart attempts to prevent a failing application from exhausting cluster CPU, memory, and API server resources.
Diagnosing a crashing pod requires a systematic troubleshooting workflow to isolate application exceptions, resource constraints, and health probe failures. In this comprehensive technical guide, we break down common container exit codes and walk you through step-by-step kubectl commands to recover your workloads. If your organization requires high-availability cluster architecture or cloud migration, explore our specialized cloud and DevOps infrastructure services.
1. What Causes the Kubernetes CrashLoopBackOff Error

According to the official Kubernetes documentation, a pod enters the CrashLoopBackOff state when its container terminates unexpectedly and restarts repeatedly. Five primary root causes account for the majority of crash loops:
- Application Runtime Exceptions (Exit Code 1): Unhandled code errors, missing configuration files, missing database connections, or unparsed environment variables cause the application process to terminate immediately after startup.
- OOMKilled Memory Exhaustion (Exit Code 137): The container attempts to allocate more RAM than allowed by its
resources.limits.memoryspecification. The Linux kernel Out-Of-Memory (OOM) killer immediately terminates the container. - Failed Liveness Probes: Kubernetes liveness probes check application responsiveness. If the probe configuration fails or times out before the application finishes warming up, the kubelet kills and restarts the container.
- Missing ConfigMaps or Secrets: If a deployment references an environment variable from a ConfigMap or Secret that does not exist in the namespace, the container fails before execution starts.
- Short-Lived Entrypoint Commands: Docker containers require a long-running foreground process (PID 1). If the container entrypoint runs a short command (like a shell script without a blocking loop), the container exits with code 0 and Kubernetes restarts it repeatedly.
Important Insight: The Power of the Previous Logs Flag
When a pod is stuck in CrashLoopBackOff, running kubectl logs <pod-name> often shows an empty output because the container is currently terminated. Always add the --previous flag (kubectl logs <pod-name> --previous) to view stderr logs from the crashed container before it restarted.
2. Step-by-Step Diagnostic Workflow
Execute these three essential diagnostic steps in your terminal to pinpoint the exact failure point:
Step 1: Inspect Pod Status and Last State
Run kubectl describe pod to inspect the container state, termination reason, and event history:
# Describe the failing pod
kubectl describe pod <pod-name> -n <namespace>Examine the Containers section in the output. Look specifically at:
- Last State: Check
Exit Code(e.g., 1, 137, 255) andReason(e.g.,ErrororOOMKilled). - Events: Look at the chronological event log at the bottom for messages like
Liveness probe failedorBack-off restarting failed container.
Step 2: Inspect Previous Container Logs
Retrieve the output emitted right before the crash occurred:
# View stderr and stdout from the crashed instance
kubectl logs <pod-name> --previous -n <namespace>
# For multi-container pods, specify the container name
kubectl logs <pod-name> -c <container-name> --previous -n <namespace>Step 3: Temporarily Override the Entrypoint for Interactive Debugging
If logs are inconclusive, temporarily override the container command to keep the container running indefinitely, allowing you to shell into the environment:
# In your deployment YAML, override command temporarily
spec:
containers:
- name: my-app
image: my-app:latest
command: ["sleep", "3600"]Apply the manifest, wait for the pod to reach Running, and exec into the container with kubectl exec -it <pod-name> -- /bin/sh to inspect environment variables and configuration files directly.
3. Tested Solutions for Common Crash Scenarios
Solution A: Fixing OOMKilled Memory Limits (Exit Code 137)
If the termination reason is OOMKilled, your application exceeded its hard memory ceiling. Increase the memory limit and set a realistic memory request:
resources:
requests:
memory: "512Mi"
cpu: "250m"
limits:
memory: "1Gi"
cpu: "1000m"Solution B: Adjusting Premature Liveness Probes
If your application requires 15 to 30 seconds to compile caches, connect to databases, or warm up JVM runtimes, an early probe will kill the process before it reports ready. Add initialDelaySeconds:
livenessProbe:
httpGet:
path: /healthz
port: 8080
initialDelaySeconds: 30
periodSeconds: 10
failureThreshold: 3
timeoutSeconds: 54. Kubernetes Exit Code Reference Guide
| Exit Code | Signal / Name | Root Cause | Resolution |
|---|---|---|---|
| Exit Code 0 | Success / Completed | Foreground process exited normally | Ensure foreground service keeps running |
| Exit Code 1 | Application Error | Code crash, syntax error, missing env var | Inspect kubectl logs --previous |
| Exit Code 137 | SIGKILL / OOMKilled | Exceeded memory resource limits | Increase resources.limits.memory |
| Exit Code 143 | SIGTERM | Graceful shutdown requested by kubelet | Check probe failures or preStop timeouts |
For more architectural guides on containerization and cloud orchestration, read our technical walkthrough on fixing Docker port allocation conflicts or review our guide on setting up automated CI/CD with GitHub Actions. For custom Kubernetes cluster management and production support, reach out via our contact page.
5. Where to Go From Here
CrashLoopBackOff indicates that Kubernetes is functioning as intended by preventing unstable containers from consuming cluster resources. Establish these long-term deployment standards across your team:
- Always configure both
requestsandlimitsfor memory and CPU to give the Kubernetes scheduler accurate placement signals. - Use
readinessProbesto control traffic routing and separate them fromlivenessProbesto avoid killing pods during temporary latency spikes. - Stream all application error output to standard error (stderr) rather than local container files so
kubectl logscaptures crashes reliably.