🚨 Azure Error: AKS 'CrashLoopBackOff' — Cause, Fix, and Troubleshooting Guide

Overview

CrashLoopBackOff on AKS means a container starts, exits, and Kubernetes restarts it — repeatedly — applying an exponential back-off between attempts. It is a status, not a root cause: the container is dying for some reason and the kubelet is throttling the restart loop. The literal state from kubectl get pods:

NAME                        READY   STATUS             RESTARTS      AGE
api-7d9c8b6f5-4kq2n         0/1     CrashLoopBackOff   6 (48s ago)   4m12s

And the container’s last state carries the exit code that points at the cause:

    Last State:     Terminated
      Reason:       Error
      Exit Code:    1
      Started:      Sat, 12 Jul 2026 14:02:10 +0000
      Finished:     Sat, 12 Jul 2026 14:02:11 +0000

The job is to find why the process exits — the exit code, logs, probes, and config tell you.

Symptoms

• A pod cycles through Running → Error/Completed → CrashLoopBackOff with a climbing RESTARTS count.
• READY never reaches 1/1; the app is unavailable behind its Service.
• Restarts slow down over time (back-off up to five minutes) even though the container starts instantly.
• Rollouts stall because new replicas never become ready.

Common Root Causes

• Application error on startup — an unhandled exception, missing dependency, or bad code path exits non-zero (exit code 1).
• Missing/wrong configuration — a required env var, mounted secret, or config file is absent, so the app aborts immediately.
• Failing liveness probe — an overly aggressive livenessProbe kills a container that is actually still starting (pair with startupProbe).
• OOMKilled — the container exceeds its memory limit and is killed (exit code 137), then restarts and dies again.
• Bad command/entrypoint — a wrong command/args or a binary that is not executable (exit code 127/126).
• Dependency not ready — the app crashes because a database, Key Vault, or downstream service is unreachable at boot.

How to diagnose

Read the logs of the current and the previous (crashed) container instance — the previous one holds the failure:

kubectl logs api-7d9c8b6f5-4kq2n
kubectl logs api-7d9c8b6f5-4kq2n --previous

Get the exit code and reason, plus events:

kubectl describe pod api-7d9c8b6f5-4kq2n
kubectl get pod api-7d9c8b6f5-4kq2n \
  -o jsonpath='{.status.containerStatuses[0].lastState.terminated.exitCode}{"\n"}'

Exit code cheat sheet: 137 = OOMKilled (or SIGKILL), 1 = generic app error, 126 = not executable, 127 = command not found, 139 = segfault.

Check whether a liveness probe is the killer:

kubectl get pod api-7d9c8b6f5-4kq2n \
  -o jsonpath='{.spec.containers[0].livenessProbe}'; echo

For config/secret problems (common with AKS + Key Vault CSI or managed identity), verify the mounts and env exist:

kubectl describe pod api-7d9c8b6f5-4kq2n | grep -A15 "Mounts:\|Environment:"

Fixes

Fix the application/config cause the logs reveal — supply the missing env var or secret, correct the connection string, or fix the startup bug. For a missing secret via the Key Vault CSI driver, ensure the SecretProviderClass and workload identity are correct so the mount populates.

Raise memory limits for OOMKilled (exit 137):

resources:
  requests:
    memory: "512Mi"
  limits:
    memory: "1Gi"

Stop a premature liveness kill by adding a startupProbe (or loosening initialDelaySeconds) so slow-starting apps are not killed mid-boot:

startupProbe:
  httpGet: { path: /healthz, port: 8080 }
  failureThreshold: 30
  periodSeconds: 10
livenessProbe:
  httpGet: { path: /healthz, port: 8080 }
  initialDelaySeconds: 0
  periodSeconds: 15

Correct a bad entrypoint (exit 126/127) — fix command/args or the image so the binary exists and is executable.

Handle dependency-at-boot by making startup tolerant (retry/wait) or gating readiness on the dependency rather than crashing.

After changing the manifest, roll it out and watch the pod recover:

kubectl apply -f deployment.yaml
kubectl get pods -w

What to watch out for

• --previous logs are gold. The live container may be too young to log anything useful; the previous instance’s logs contain the actual crash.
• Liveness vs readiness. A failing readiness probe removes a pod from the Service but does not restart it; only liveness causes restarts. Do not use liveness for slow startup — use startupProbe.
• Exit 137 isn’t always OOM. It can be any SIGKILL (e.g., failed liveness); confirm with the OOMKilled reason in describe.
• Back-off is expected. The increasing delay between restarts is Kubernetes protecting the node, not an additional fault — fix the root cause and the loop clears.

Related

• AKS ImagePullBackOff — the pod never starts because the image cannot be pulled, a step before CrashLoopBackOff.
• AKS node NotReady — node-level failures that can masquerade as pod problems.
• Troubleshooting AKS with AI — a broader AKS debugging workflow and prompts.