Diagnosing Kubernetes CrashLoopBackOff: A Systematic Guide

Identifying the Failure Pattern

When a pod shows a CrashLoopBackOff status, it means the kubelet is restarting a container that exits immediately. The exit code and event details reveal the root cause.

Exit Code	Meaning	Common Root Cause
1	General Error	Application logic, missing env vars, config errors.
137	OOMKilled	Container exceeded memory limit.
143	SIGTERM	Graceful termination, often from liveness probe failure.
127	Command Not Found	Entrypoint or binary missing.

Step 1: Inspect Pod Metadata

Run the following command on the node where the pod is scheduled:

kubectl describe pod <pod-name> -n <namespace>

Look at the Containers: section and check the LastState block. The Reason field tells you why the previous instance died. Scroll to the Events: section for clues such as Liveness probe failed or OOMKilled.

Step 2: Retrieve Previous Logs

Because the current container is in a restart loop, kubectl logs shows the output of the newest instance. To see what the crashed instance printed, use --previous:

kubectl logs <pod-name> --previous -n <namespace>

If the pod has multiple containers, add -c <container-name>. Search for stack traces, configuration errors, or permission messages that occurred right before the exit.

Step 3: Validate Resources and Configuration

3.1 Memory Limits (Exit Code 137)

When the exit code is 137, the kernel OOM killer terminated the process. Increase the memory limit in the deployment spec:

resources:
  limits:
    memory: "512Mi"
    cpu: "500m"
  requests:
    memory: "256Mi"

After editing the manifest, apply and rollout:

kubectl apply -f deployment.yaml
kubectl rollout restart deployment <deployment-name>

3.2 Liveness Probe Timeouts

If the pod is healthy but slow to start, the liveness probe may be killing it. Adjust the probe parameters:

livenessProbe:
  httpGet:
    path: /healthz
    port: 8080
  initialDelaySeconds: 30
  periodSeconds: 10

3.3 Missing Environment Variables or Volumes

Check that all required env entries, configMapKeyRef, and secretKeyRef objects exist. Verify volume mounts point to existing paths inside the container and that the container has write permissions where needed.

Verification and Escalation

After applying a fix, monitor the pod:

kubectl get pods -n <namespace> -w

If the pod transitions to Running and stays there for several minutes, the issue is resolved. If it re-enters CrashLoopBackOff, re‑run kubectl describe pod to see new events. Use kubectl top nodes to confirm the node is not under overall resource pressure. If the problem persists despite all local fixes, consider raising an issue with the application maintainer or the cluster administrator.