Kubernetes CrashLoopBackOff: How to Debug a Restarting Pod

CrashLoopBackOff is a pod status, not a root cause. It means a container in the pod started, exited, and Kubernetes is waiting longer and longer before restarting it. The delay grows exponentially, starting at 10 seconds and capped at 5 minutes, and the timer resets after the container runs cleanly for 10 minutes. The reason is always in the container's exit, so read that first.

NAME                   READY   STATUS             RESTARTS      AGE
web-7c9f6d8b5-x2k4p    0/1     CrashLoopBackOff   6 (45s ago)   9m

Check in this order

1. Describe the pod and read the last state.
2. Read the logs of the previous (crashed) container.
3. Decode the exit code.
4. Check probes, resources and configuration that the app needs at startup.
5. Run the image yourself to reproduce.

Step 1: describe the pod

kubectl describe pod web-7c9f6d8b5-x2k4p

Look at Last State, Reason, Exit Code, and the Events at the bottom:

Last State:     Terminated
  Reason:       OOMKilled
  Exit Code:    137

The Reason column often answers the question outright: OOMKilled, Error, Completed, or ContainerCannotRun.

Step 2: read the right logs

A restarting container's current log may be empty. Ask for the previous instance:

kubectl logs web-7c9f6d8b5-x2k4p --previous
kubectl logs web-7c9f6d8b5-x2k4p -c sidecar --previous   # multi-container pod
kubectl logs deploy/web --all-containers --previous

A stack trace, "cannot connect to database", "missing env var" or "permission denied" here is usually the whole story.

Step 3: decode the exit code

Common causes and fixes

Out of memory

OOMKilled means the container exceeded resources.limits.memory. Raise the limit or reduce usage:

resources:
  requests: { memory: "256Mi", cpu: "100m" }
  limits:   { memory: "512Mi" }

For runtimes like Node.js and the JVM, set the heap below the limit; see Node.js heap out of memory.

Liveness probe killing a healthy but slow app

If events show Liveness probe failed followed by a restart, the app may just need more time to start. Add a startupProbe and loosen the liveness probe:

startupProbe:
  httpGet: { path: /healthz, port: 8080 }
  failureThreshold: 30
  periodSeconds: 5
livenessProbe:
  httpGet: { path: /healthz, port: 8080 }
  periodSeconds: 10
  failureThreshold: 3

Make sure the probe's port and path match what the app really serves. A probe on the wrong port restarts a perfectly good container forever. The load balancer health checks guide explains good endpoint design.

Bad command, entrypoint or image

Exit 126 or 127, or an immediate exit with no logs, often means the command or args override is wrong, a script lacks the execute bit, or the image was built for another CPU architecture (exec format error). Reproduce locally:

docker run --rm -it --entrypoint sh your-image:tag

Missing configuration or dependencies

Required environment variables, mounted ConfigMaps or Secrets, or an unreachable database cause startup crashes. Check:

kubectl get configmap,secret -n <ns>
kubectl describe pod <pod> | grep -A5 -i -E "Mounts|Environment"

A missing Secret or ConfigMap reference shows as CreateContainerConfigError rather than CrashLoopBackOff. If the app depends on another service that is not ready yet, add retries or an init container.

File permissions and read-only filesystems

With securityContext.readOnlyRootFilesystem: true or a non-root runAsUser, an app that writes to /tmp or its working directory crashes. Mount an emptyDir volume at the path it needs.

The process exits normally

A container whose main process finishes (a shell that runs a command and returns, or a daemon that forks into the background) ends with exit 0, and a Deployment restarts it. Run the process in the foreground, or use a Job or CronJob for finite work.

Debugging tools

kubectl get events --sort-by=.lastTimestamp -n <ns>
kubectl debug -it <pod> --image=busybox:1.36 --target=<container>

kubectl debug attaches an ephemeral debug container, so you can inspect the environment of a pod that keeps dying. To keep a crashing container alive for inspection, temporarily override its command with sleep 3600 in a copy of the deployment.

Verify the fix

kubectl rollout status deploy/web
kubectl get pods -w

Wait for READY 1/1 and a stable restart count. Then check the public URL with the वेबसाइट हेल्थ चेक and keep an uptime monitor on it. If traffic still fails after pods are ready, move on to Ingress 502 and 503.

अगले कदम

• Image will not even start? See ImagePullBackOff.
• Check traffic through the ingress: Kubernetes Ingress 502/503.
• Understand memory kills in Docker exit code 137.
• Monitor the service with an uptime monitor.

सामान्य प्रश्न

How long does CrashLoopBackOff wait between restarts?

The delay doubles from 10 seconds up to a 5-minute maximum, and resets after a container runs for 10 minutes without crashing. Recent Kubernetes releases may tune these values, so check the current docs for your version.

Why are the logs empty?

You are probably reading the new, just-started container. Use kubectl logs --previous to read the one that crashed.

Is CrashLoopBackOff the same as ImagePullBackOff?

No. ImagePullBackOff means the image could not be fetched. CrashLoopBackOff means the image ran and the process exited.

Can I force an immediate restart?

Deleting the pod (kubectl delete pod <name>) creates a fresh one with no backoff, but it will crash again if the cause remains.

यह पेज सामान्य जानकारी है, जिसे हमारी संपादकीय टीम ने लिखा है और दस्तावेज़ीकरण बदलने पर अपडेट किया जाता है। सर्वर और प्रदाता अलग-अलग होते हैं, इसलिए बदलाव पहले सुरक्षित तरीके से जाँचें। देखें: संपादकीय नीति और अस्वीकरण.