How to Debug a Crash-Looping Container

Quick answer
A crash-looping container starts, dies, and restarts repeatedly — usually within seconds of booting.
The first move is always the logs: the crash reason is almost always in the most recent container logs.
Work through the checklist — status, logs, entrypoint, config, resources — in that order, and the cause appears.

What is a crash loop and how do I see it?

A crash loop is a container that keeps starting and dying: the platform restarts it, it dies again, forever. Docker shows the status as Restarting; Kubernetes shows CrashLoopBackOff. The first diagnostic is the container’s recent logs — docker logs or kubectl logs — because the process usually prints its fatal error before exiting. If the logs are empty, the failure is happening before your app runs: the entrypoint or startup environment.

# The first three commands of any crash-loop investigation
docker ps -a | grep <name>          # status: Restarting (1) 3 seconds ago
docker logs --tail 50 <container>    # the fatal error, usually here
docker inspect <container> | grep -A2 ExitCode   # exit code: 1 = app error, 127 = missing command, 137 = OOM

What are the usual causes?

In rough order of frequency: an exception at startup (missing env var, bad config, failing database connection); a command or entrypoint that doesn’t exist (typo, wrong path — exit 127); a port conflict or bind failure; missing dependencies or volumes; and resource limits (exit 137 when the kernel OOM-kills it). Container-specific gotchas: CMD runs a shell that exits immediately, or the entrypoint script fails silently before exec’ing the app.

How do I fix it systematically?

Work the list in order. Logs first — fix what they say. Then reproduce locally: run the same image with the same env vars and see the error instantly, with full output. Check the entrypoint and CMD against the image’s declared ones (docker inspect shows both). Verify config and secrets are mounted where the app expects. Finally, check resource limits — a container restarting every few seconds with empty logs and exit 137 is almost always memory.

Where this bites vibecoders
The first production moment for many vibecoded apps is a container that won’t stay up, and the AI assistant’s suggestions (‘restart it’, ‘increase resources’, ‘try again’) skip the one tool that solves it: reading the logs. The systematic checklist — logs, exit code, local repro, entrypoint, resources — turns a panic into a procedure. Notably, exit 137 (OOM) with no logs is the signature of the memory leak patterns assistants generate.

Where AI coding assistants get this wrong

Suggesting restarts and resource increases before reading the crash logs.
Writing entrypoints that fail silently (missing exec, backgrounded processes) so the crash has no log line.
Ignoring exit codes, which discriminate the cause faster than any other signal.
Handing back ‘works on my machine’ without reproducing with the same env vars and image.

Checklist

Read the recent container logs first — the cause is usually printed there.
Check the exit code: 1 (app error), 127 (missing command), 137 (OOM).
Reproduce locally with the same image and environment variables.
Verify entrypoint, CMD, mounted config, and resource limits in that order.

FAQ

What does exit code 137 mean?

137 means the process was killed by signal 9 (SIGKILL) — almost always the OOM killer because the container exceeded its memory limit. The classic signature: empty logs, quick restart loop, exit 137. Raise the limit after checking for a leak, or cap the workload.

Why are the logs empty when the container is crashing?

The crash is happening before your app produces output: the entrypoint script failed, the command doesn’t exist, or the process was killed externally (OOM). Run the image locally with the same environment and the error becomes visible immediately.