Skip to main content

Runbooks / kubernetes-crashloopbackoff

Kubernetes CrashLoopBackOff

A pod restarts in a loop and its container status shows CrashLoopBackOff — find the exit reason from the pod spec and logs before reaching for restarts.

12 canonical sections · 3 command blocks · last reviewed · updated 2026-09-21

Related focus areas:CloudOpsPlatform EngineeringSRE

Fix the underlying gap:AWS Security ImprovementCloud Cost OptimizationIncident Management MaturityObservability MaturityPlatform Engineering AdoptionProduction-Ready KubernetesResilience and DR ImprovementSRE Adoption

On this page
  1. Symptoms
  2. Severity / impact
  3. Immediate safety actions
  4. Fast checks
  5. Diagnostic commands
  6. Likely causes
  7. Decision tree
  8. Remediation
  9. Verification
  10. Escalation
  11. Prevention
  12. Related metrics / alerts
  13. Sources

Symptoms

  • kubectl get pods shows CrashLoopBackOff with a climbing RESTARTS column; the workload's availability drops or never comes up after a rollout.
  • Alerts: KubePodCrashLooping firing; service-level 5xx or capacity loss downstream if the pod backs a serving workload.

Severity / impact

  • Sev-3 for a redundant deployment with healthy siblings absorbing traffic; Sev-1 for a singleton (the thing simply does not exist while it crash-loops) or when the crash-looping pod holds a leader lease others wait on.

Immediate safety actions

  • Do NOT delete the pod yet — its lastState holds the exit code and the previous logs; deleting destroys the evidence.
  • If a rollout just started and the previous ReplicaSet was healthy, kubectl rollout undo restores service first; triage the bad revision afterwards.
  • Freeze CI/CD for that service so a "fix" deploy does not stack on an unknown cause.

Fast checks

  • kubectl describe pod: exit code and reason in lastState.terminated (Error/OOMKilled), and whether probes kill it before it is ready.
  • Application logs of the PREVIOUS container (--previous), not the current one — the current one usually has nothing useful.
  • Did anything change? Rollout event, configmap/secret edit, secret rotation expiry, node migration to a different image pull policy.

Diagnostic commands

kubectl get pod -n <ns> <pod> -o jsonpath='{.status.containerStatuses[0].lastState.terminated.exitCode}'
kubectl logs -n <ns> <pod> --previous --tail=100
kubectl describe pod -n <ns> <pod> | sed -n '/Events/,$p'

Likely causes

1. Application exits on boot: bad config, missing env var, unreachable dependency at startup (most common). 2. OOMKilled: container memory limit lower than the app's steady-state footprint. 3. Liveness probe too aggressive: kills the pod during slow start (JVM warmup, migrations) — RESTARTS climbs while the app would have become healthy. 4. Command/args error: wrong entrypoint, missing file, wrong user permissions on a mounted volume.

Decision tree

  • Exit code 1 with an application error in previous logs → config/dependency problem: fix the config, no probe changes needed.
  • Exit code 137 + OOMKilled reason → raise the memory limit to observed usage × 1.5, then investigate the leak if usage still grows.
  • Exit code 137 but NOT OOMKilled → liveness probe is killing it: check probe timeout/failureThreshold vs startup time.
  • Exit code 126/127 → entrypoint problem: wrong command or missing binary — check the image tag actually deployed.

Remediation

  • Config/boot error: correct the configmap/secret, then restart the pod deliberately (kubectl delete pod after evidence captured).
  • OOMKilled: raise resources.limits.memory; for a leak, add a restart policy (vertical autoscaler or cron) as a stopgap and file the leak as a bug with a heap dump.
  • Probe kills: add a StartupProbe or lower liveness failureThreshold; never "fix" this by deleting the liveness probe.
  • Roll out with maxUnavailable: 0 so a bad revision cannot take the last healthy pod with it.

Verification

  • RESTARTS stops climbing for 10+ minutes and the pod reports Ready.
  • The workload's own health endpoint and golden signals (latency/errors) are green — Ready pods can still be broken inside.
  • If OOM was the cause: memory graph shows the new limit has ≥30% headroom at peak.

Escalation

  • Service owners for app-level boot failures (they own the config); platform team for node-level or image-registry issues; if a leader-lease singleton is down, page the on-call for that system explicitly.

Prevention

  • Startup probes on every slow-starting workload so liveness never races initialization.
  • Memory limits set from observed usage, not guesses; alert at 80% of limit.
  • kubectl rollout undo drilled in game days — rollback under pressure must be muscle memory.

Sources

Know which failure modes you actually have?

A free OpsRoadmaps assessment scores your controls with explainable findings and builds a prioritized roadmap — runbook coverage is one of the things it measures.

Assess my stack

Runbooks document self-reported practice. Commands and thresholds were last reviewed 2026-09-21 — verify against your own environment before acting.