Kubernetes CrashLoopBackOff: How to Fix It Step by Step

You deploy a change, check the cluster, and there it is: a pod stuck on CrashLoopBackOff. It restarts, fails, waits, and restarts again. It feels like Kubernetes is mocking you.

The good news is that Kubernetes CrashLoopBackOff is not a mysterious bug. It is a symptom with a short list of usual causes. In this guide I will show you a calm, repeatable way to find the reason and fix it, using only a few kubectl commands.

What does Kubernetes CrashLoopBackOff mean?

CrashLoopBackOff means a container in your pod starts, exits with an error, and then keeps getting restarted. After each failure, the kubelet waits a little longer before trying again. According to the Kubernetes documentation on the pod lifecycle, this delay grows step by step up to a cap of a few minutes. That growing delay is the “back-off” in the name.

Two things are worth remembering. First, CrashLoopBackOff is a status, not a root cause. Second, the real answer is almost always in the container’s logs, its exit code, or the pod’s events.

The most common causes

• The application crashes on start: a bug, a bad flag, or a missing environment variable.
• Out of memory: the container hits its memory limit and is killed.
• A failing liveness probe: Kubernetes restarts a healthy but slow-starting app.
• Wrong command or arguments: the entrypoint does not exist or exits at once.
• A missing dependency: the app cannot reach a database or another service and gives up.
• Permissions or file problems: the app cannot write to a read-only path or run as the configured user.

Kubernetes CrashLoopBackOff fix: 7 easy steps

Work through these in order. Most problems are solved by step 3.

Step 1: Confirm the pod and its restart count

Start by looking at the pod’s status and how often it has restarted.

kubectl get pods -n <namespace>

A high number in the RESTARTS column confirms the loop. Note the exact pod name.

Step 2: Read the pod details

This command shows the last state, the exit code and the recent events in one place.

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

Look at the Last State, Reason and Exit Code fields, then scroll to the Events section at the bottom. The official guide to debugging running pods covers this workflow in more depth.

Step 3: Check the logs of the crashed container

The current container may have just restarted and have no useful output. Ask for the previous run instead.

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

If the pod has several containers, add -c <container-name>. A stack trace, a connection error or a “file not found” line here usually names the culprit.

Step 4: Decode the exit code

The exit code from step 2 is a strong clue:

• 1: a general application error. Read the logs closely.
• 137: the container was killed, often because it ran out of memory (look for OOMKilled).
• 139: a segmentation fault inside the app or a library.
• 143: the container received a termination signal, for example during a rollout.
• 126 or 127: the command could not run or was not found. Check the image’s entrypoint.

Step 5: Check resource limits and node pressure

If the reason is OOMKilled, the container needs more memory or the app has a leak.

kubectl top pod <pod-name> -n <namespace>
kubectl get events -n <namespace> --sort-by=.lastTimestamp

Raise the memory limit in small steps and watch the result. Also check whether the node itself is short of resources. A full disk on the node can cause odd failures, and my guide on Linux disk space full shows how to find the cause.

Step 6: Review probes, config and dependencies

Check the deployment spec for three things:

• Liveness probe: if the app needs time to start, increase initialDelaySeconds or add a startup probe so it is not killed too early.
• Environment and config: confirm every required variable, ConfigMap and Secret is present and correct.
• Dependencies: make sure the database or API the app calls is reachable from inside the cluster.

kubectl get deployment <name> -n <namespace> -o yaml

Step 7: Debug live, or roll back

If the container dies too fast to inspect, attach a temporary debug container.

kubectl debug -it <pod-name> --image=busybox --target=<container-name> -n <namespace>

If the problem started after a new release and you need service back quickly, roll back first and investigate afterwards.

kubectl rollout undo deployment/<name> -n <namespace>
kubectl rollout status deployment/<name> -n <namespace>

How to stop it coming back

• Set realistic requests and limits based on real usage, not guesses.
• Use readiness and startup probes properly, so slow starts are not mistaken for failures.
• Test images locally before deploying, and pin image versions.
• Collect logs and metrics centrally so you can see the crash after the pod is gone. My practical guide to Kubernetes observability explains how to do this well.

If you are still deciding how to package and run your workloads, this comparison of Docker vs virtual machines may help.

Common questions about Kubernetes CrashLoopBackOff

Is CrashLoopBackOff an error or a status?
It is a status. It tells you a container keeps failing and restarting, but not why. The cause is found in the logs, exit code and events.

How long does the back-off last?
The wait between restarts increases after each failure, up to a cap of a few minutes. It resets once the container runs successfully for a while.

Why are my logs empty?
The container may crash before it writes anything, or you may be reading the new instance. Use --previous to read the last crashed run.

Can a healthy app get CrashLoopBackOff?
Yes. A strict liveness probe or a low memory limit can make Kubernetes restart an app that would otherwise work.

Final thoughts

A pod in CrashLoopBackOff feels stressful, but the path is the same every time: look at the status, read the previous logs, decode the exit code, and check limits, probes and dependencies. Follow the steps in order and you will usually find the cause in minutes, not hours.

Which cause was behind your last crash loop? Tell me in the comments. It helps other readers.