Kubernetes Error: CrashLoopBackOff — Pod Restart Loop

NAME                       READY   STATUS             RESTARTS   AGE
api-7d8f6c5b9-abc12        0/1     CrashLoopBackOff   8          12m

# kubectl describe pod api-7d8f6c5b9-abc12
Last State:     Terminated
  Reason:       Error
  Exit Code:    1
  Started:      Fri, 26 Apr 2026 09:14:32 +0100
  Finished:     Fri, 26 Apr 2026 09:14:33 +0100
Events:
  Warning  BackOff  2m (x42 over 11m)  kubelet  Back-off restarting failed container

CrashLoopBackOff is the visible symptom of an invisible loop: your container starts, exits, and starts again — over and over — until the kubelet slows down the restart cadence. It’s not a single error type; it’s “your app died several times in a row and we’re rate-limiting you.” The real error is hiding in the previous container’s logs and the pod’s events.

The diagnostic sequence is fixed: kubectl logs --previous to see what the dying app said, kubectl describe pod to see how it died (Error vs OOMKilled vs probe-failed), then fix the right thing. Don’t bump memory if the issue is a missing env var; don’t disable the probe if the app genuinely isn’t healthy.

Why this happens

• Application throws on startup. Missing env var, malformed config, code-level exception during init. `kubectl logs --previous` shows the stack trace from the dying container. The app exits with code 1 (or whatever the runtime maps the exception to) and the kubelet restarts it.
• Container OOMKilled. Your container exceeded its memory limit and the kernel SIGKILLed it. Last State shows `Reason: OOMKilled, Exit Code: 137`. Fix is more memory in the resource request/limit, or reducing the working-set size of your app (the latter is usually right).
• Liveness probe failing. App boots fine but the liveness probe gets HTTP 5xx or doesn't reply within `timeoutSeconds`, so the kubelet decides the container is unhealthy and kills it. Common when the app's liveness endpoint depends on a slow downstream — make the probe shallow.
• Wrong command or arg. Container starts but the entrypoint exits immediately. Could be a typo in `command:`, a missing binary in the image, a script that runs `exit 1`, or an init script that depends on a file that wasn't mounted yet.
• Boot-time dependency unavailable. App connects to Postgres/Redis/etcd in its `init()` and exits if the connection fails. On a cold cluster start, the dependency may not be ready yet. The fix is retry-with-backoff in the app or a proper init container that waits.

How to fix it

Fixes are ordered by likelihood. Start with the first one that matches your context.

# The pod is currently restarting; --previous shows the dying container's logs.
kubectl logs <pod> -n <namespace> --previous

# If the container has multiple containers in one pod:
kubectl logs <pod> -c <container-name> --previous

# Tail logs as the new instance starts (sometimes catches startup faster):
kubectl logs <pod> -n <namespace> -f

kubectl describe pod <pod> -n <namespace>

# Look for these indicators:
#   Last State: Terminated
#     Reason: OOMKilled        ← memory limit
#     Reason: Error            ← app exited non-zero
#     Exit Code: 137           ← SIGKILL (OOM or kubelet)
#     Exit Code: 143           ← SIGTERM (graceful shutdown signal)
#
# In Events, look for:
#   Liveness probe failed: ...
#   Readiness probe failed: ...

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
spec:
  template:
    spec:
      containers:
        - name: api
          image: myregistry.example/team/api:v2.3.1
          resources:
            requests:
              cpu: 200m
              memory: 512Mi
            limits:
              cpu: 1000m
              memory: 1Gi    # raise this if OOMKilled
          livenessProbe:
            httpGet:
              path: /healthz
              port: 8080
            initialDelaySeconds: 30
            periodSeconds: 10
            timeoutSeconds: 3
            failureThreshold: 3

# Shallow liveness — just confirms the HTTP server is up.
livenessProbe:
  httpGet: { path: /healthz, port: 8080 }
  periodSeconds: 10
  timeoutSeconds: 2
  failureThreshold: 3

# Readiness can be deeper — checks downstream deps.
readinessProbe:
  httpGet: { path: /ready, port: 8080 }
  periodSeconds: 5
  timeoutSeconds: 3

# Startup gives slow-booting apps up to 5 minutes before liveness fires.
startupProbe:
  httpGet: { path: /healthz, port: 8080 }
  periodSeconds: 10
  failureThreshold: 30   # 30 * 10s = 5 minutes

Detection and monitoring in production

Alert on `kube_pod_container_status_restarts_total` rate (Prometheus + kube-state-metrics) — a pod restarting more than ~5 times in 10 minutes is in or near CrashLoopBackOff regardless of the official phase. Pair with an OOMKill alert (`container_oom_events_total`). Track CrashLoopBackOff incidents by deployment to spot bad releases fast — a fresh deploy that immediately CrashLoops should auto-rollback.