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
Symptoms
kubectl get podsshowsCrashLoopBackOffwith a climbing RESTARTS column; the workload's availability drops or never comes up after a rollout.- Alerts:
KubePodCrashLoopingfiring; 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
lastStateholds the exit code and the previous logs; deleting destroys the evidence. - If a rollout just started and the previous ReplicaSet was healthy,
kubectl rollout undorestores 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 inlastState.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=100kubectl 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 +
OOMKilledreason → 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 podafter 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: 0so 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 undodrilled 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 stackRunbooks document self-reported practice. Commands and thresholds were last reviewed 2026-09-21 — verify against your own environment before acting.