Guides

Kubernetes CrashLoopBackOff: Causes and How to Fix It (Step by Step)

By Ravindra Bagale, AWS & DevOps trainer · LinkedIn · Published: 16 October 2026 · Last updated: 17 October 2026

CrashLoopBackOff means your container starts, crashes, and Kubernetes keeps restarting it, waiting a little longer each time. It is a symptom, not the cause. Run kubectl describe pod <name> to read the exit code, and kubectl logs <name> --previous to read the error of the container that crashed. The exit code tells you whether it is an app error, a wrong command, missing config, memory (OOMKilled) or a failing probe.

kubectl get pods                          # 1. STATUS = CrashLoopBackOff, RESTARTS keeps growing
kubectl describe pod orders-api-7d9f-x2k  # 2. Last State: Terminated, Reason, Exit Code
kubectl logs orders-api-7d9f-x2k --previous   # 3. the real error from the crashed container
kubectl get deploy orders-api -o yaml     # 4. check env, command, resources, probes

A live example first

Friends, let us see the error before the theory. Here is a small lab cluster (kind on a laptop, the same on Amazon EKS). We deploy the official postgres:16 image, but we forget the password variable:

kubectl create deployment db --image=postgres:16
kubectl get pods

NAME                  READY   STATUS             RESTARTS      AGE
db-6c8d7b9f5d-q8l2m   0/1     CrashLoopBackOff   4 (32s ago)   2m

Now the old logs:

kubectl logs db-6c8d7b9f5d-q8l2m --previous

Error: Database is uninitialized and superuser password is not specified.
       You must specify POSTGRES_PASSWORD to a non-empty value for the
       superuser.

There is the cause in plain English. It is not a Kubernetes problem at all. The app refused to start without its config. The fix is one line:

kubectl create secret generic db-pass --from-literal=POSTGRES_PASSWORD='Lab@12345'
kubectl set env deployment/db --from=secret/db-pass
kubectl get pods -w

After about 20 seconds the pod shows 1/1 Running and the restarts stop. That is the whole method: read, don't guess.

Why does Kubernetes say CrashLoopBackOff?

The kubelet on the node starts your container. When the main process exits, the kubelet restarts it (because restartPolicy: Always). If it keeps dying, the kubelet waits 10 seconds, then 20, then 40, up to 5 minutes between tries. That growing wait is the back-off. So the pod is not "broken by Kubernetes". Your process is exiting, and Kubernetes is politely trying again.

How do I fix CrashLoopBackOff step by step?

1. Run kubectl get pods and note the pod name and the RESTARTS count.
2. Run kubectl describe pod <name> and scroll to Last State.
3. Write down Reason and Exit Code.
4. Run kubectl logs <name> --previous and read the last 20 lines.
5. If the pod has more than one container, add -c <container>.
6. Match the exit code in the table below.
7. Change the Deployment YAML, not the pod.
8. Run kubectl apply -f deploy.yaml.
9. Run kubectl get pods -w and wait until RESTARTS stops growing.

What the exit code tells you

Exit code 0: the "it worked, but it stopped" trap

Many students build an image whose CMD runs a script that starts the server in the background and then ends. The script exits with 0, so the container stops, and Kubernetes restarts it forever. The fix is to run the server in the foreground, for example nginx -g 'daemon off;' instead of service nginx start.

Common causes, stack by stack

The same symptom has a different look in every language. Here is what the --previous log usually shows.

Java / Spring Boot

APPLICATION FAILED TO START
Failed to configure a DataSource: 'url' attribute is not specified

Fix: set SPRING_DATASOURCE_URL from a ConfigMap or Secret. Spring Boot is also slow to start, so give it a startupProbe on /actuator/health.

Node.js

Error: Cannot find module '/app/server.js'

Fix: the WORKDIR or COPY path in the Dockerfile does not match the CMD. Run docker run --rm -it image sh and ls /app to see what is really inside.

Python (Flask / Django with Gunicorn)

ModuleNotFoundError: No module named 'psycopg2'

Fix: the package is missing from requirements.txt, or it was installed in a different build stage. Rebuild and push a new tag.

Go

exec /app/server: no such file or directory

Fix: the binary was built for glibc but the image is Alpine (musl). Build with CGO_ENABLED=0 for a static binary.

.NET

Unhandled exception. System.IO.FileNotFoundException: appsettings.Production.json

Fix: mount the config file with a ConfigMap, or set ASPNETCORE_ENVIRONMENT to the file you actually ship.

nginx

nginx: [emerg] host not found in upstream "api" in /etc/nginx/conf.d/default.conf

Fix: the Service name in proxy_pass does not exist in this namespace. Create the Service first, or use the full name api.default.svc.cluster.local.

What if the container dies too fast to debug?

Override the command for a few minutes, so the container stays alive and you can look inside:

    command: ["sleep", "3600"]

Then:

kubectl exec -it deploy/orders-api -- sh
env | sort            # are the variables there?
ls -l /app            # are the files there?
/app/start.sh         # run the real start command and read the error

Remove the override when you are done. Never leave a debug sleep in production.

Real incidents: why careful restarts matter

• Reddit, March 2023 (Pi Day outage): Reddit's public post-mortem explains that a Kubernetes version upgrade went wrong because of an old node label used by their Calico network setup. The site was down for about 5 hours. The lesson for us: read the real error first, and test upgrades on a copy of the cluster.
• Monzo, October 2017: Monzo's write-up describes how a combination of Kubernetes, etcd and their linkerd service mesh stopped requests between services, and the bank's app was down for about 1.5 hours. Pods looked "up" but could not talk to each other, which is why we always check logs and events, not only the STATUS column.

Summary table