Kubernetes pod stuck in CrashLoopBackOff

Hi, it's BlueByte. CrashLoopBackOff looks alarming, but it is just Kubernetes telling you a container keeps exiting right after it starts. It is a symptom, not a cause. Let's read the two things that actually name the cause — the previous container's logs and its exit code — and fix the real problem instead of guessing.

What CrashLoopBackOff is (and isn't)

A pod never reaches Running:

NAME        READY   STATUS             RESTARTS   AGE
api-7d9f    0/1     CrashLoopBackOff   5          3m

The container starts, exits, and the kubelet restarts it — backing off longer each time (10s, 20s, 40s, up to five minutes). The status is the loop, not the reason. The reason is whatever makes the container exit, and it is in the logs and the exit code.

The handful of causes, each with a fingerprint

The main process is terminating shortly after start. The common reasons, each recognizable:

• Application error on startup — a missing env var, an unreachable dependency (a database that is not up yet), or bad config. Exit code usually 1 or 2, with a stack trace in the logs.
• Out of memory — the container exceeded its memory limit and was killed. Exit code 137 (SIGKILL), reason OOMKilled.
• A liveness probe that fails because the app is slow to start.
• A wrong command or entrypoint — the process exits immediately or the binary is not found, often with empty logs.
• A missing volume or secret, so the app cannot read its config and bails out.

Read the previous container's logs and exit code

This is the whole job. Read the instance that already crashed, not the one starting now:

kubectl logs api-7d9f --previous

Then the exit code and reason:

kubectl describe pod api-7d9f

Look at Last State: Terminated. 137 with OOMKilled is memory; 1/2 is an application error the log explains; a Liveness probe failed event points at the probe; and the Events list calls out a missing ConfigMap, Secret, or mount.

Fix the specific cause

• Application error: set the missing env var, correct the config, or make the dependency reachable, then let the pod restart.
• OOMKilled (137): raise the memory limit or reduce usage:

resources:
  limits:
    memory: "512Mi"

• Liveness probe too strict: give the app time to start:

livenessProbe:
  httpGet: { path: /healthz, port: 8080 }
  initialDelaySeconds: 30

A real case: a missing env var

kubectl get pods shows api-7d9f at CrashLoopBackOff with six restarts. kubectl logs api-7d9f --previous prints Error: DATABASE_URL is not set and nothing else, and kubectl describe pod confirms Exit Code: 1. The cause is clear — not memory, not the probe. You add DATABASE_URL to the deployment's env (or the referenced Secret), apply it, and the next restart reaches Running with the count frozen. Reading the previous log first saved you from raising memory limits that were never the problem.

Confirm it settles

Watch the pod:

kubectl get pod api-7d9f -w

It should move to Running at READY 1/1 and stop incrementing RESTARTS. If restarts keep climbing, the log names a cause you have not addressed yet.

How this differs from ImagePullBackOff and Pending

ImagePullBackOff looks similar in kubectl get pods but the image never started — the name or registry credentials are wrong. Pending means the pod has not been scheduled (no node has room). CrashLoopBackOff means the container did run and then exited, so it is the only one where the logs and exit code are your map. Set memory limits deliberately, keep probes generous, and wait for dependencies with an init container so the pod holds instead of looping.