Use when a running container crashes, exits unexpectedly, or behaves incorrectly at runtime. Prevents misdiagnosis of OOM kills, permission denied errors, and silent container exits by following the logs-exec-inspect-events workflow. Covers exit codes, OOMKilled, port conflicts, exec format error, read-only filesystem, PID limits, resource exhaustion debugging. Keywords: docker logs, docker inspect, OOMKilled, exit code 137, permission denied, port already in use, SIGTERM, SIGKILL, docker exec, exits immediately, container won't start, restart loop, out of memory, container crashes, why did my container stop.
Instrucciones de origen · Vista previa de solo lectura
name
docker-errors-runtime
description
Use when a running container crashes, exits unexpectedly, or behaves incorrectly at runtime. Prevents misdiagnosis of OOM kills, permission denied errors, and silent container exits by following the logs-exec-inspect-events workflow. Covers exit codes, OOMKilled, port conflicts, exec format error, read-only filesystem, PID limits, resource exhaustion debugging. Keywords: docker logs, docker inspect, OOMKilled, exit code 137, permission denied, port already in use, SIGTERM, SIGKILL, docker exec, exits immediately, container won't start, restart loop, out of memory, container crashes, why did my container stop.
license
MIT
compatibility
Designed for Claude Code. Requires Docker Engine 24+.
metadata
{"author":"OpenAEC-Foundation","version":"1.0"}
docker-errors-runtime
Quick Reference
Exit Code Reference
Exit Code
Signal
Meaning
Common Cause
0
—
Success
Container completed normally
1
—
Application error
Uncaught exception, failed assertion, general error
125
—
Docker daemon error
Container failed to start (invalid config, missing image)
126
—
Command not executable
Permission denied on entrypoint/cmd binary
127
—
Command not found
Binary missing in image, wrong PATH, typo in CMD
137
SIGKILL (9)
Killed
OOM killer, docker kill, or docker stop timeout
139
SIGSEGV (11)
Segmentation fault
Native library crash, memory corruption
143
SIGTERM (15)
Graceful termination
docker stop (process handled SIGTERM)
Critical Warnings
NEVER ignore exit code 137 — it ALWAYS indicates the container was forcefully killed. Check OOM events with docker inspect and dmesg before increasing memory limits blindly.
NEVER use --oom-kill-disable without setting a memory limit (-m) — the container can consume ALL host memory and crash the entire system.
NEVER assume a container that exits with code 0 is healthy — it may have completed a one-shot command instead of running as a long-lived service. ALWAYS verify the process runs in the foreground.
ALWAYS check docker logs before any other debugging step — 90% of runtime issues are explained in the application output.
ALWAYS use docker inspect --format='{{.State.ExitCode}}' to get the exact exit code — docker ps -a truncates status information.
Debugging Workflow
Step 1: Check Logs
# Last 100 lines
docker logs --tail 100 <container>
# Follow live output with timestamps
docker logs -f -t <container>
# Logs from last 5 minutes
docker logs --since 5m <container>
Step 2: Inspect Container State
# Exit code and error message
docker inspect --format='{{.State.ExitCode}}' <container>
docker inspect --format='{{.State.Error}}' <container>
# OOM killed?
docker inspect --format='{{.State.OOMKilled}}' <container>
# Full state as JSON
docker inspect --format='{{json .State}}' <container> | jq .
Step 3: Exec Into Running Container
# Interactive shell (if container is still running)
docker exec -it <container> sh
docker exec -it <container> bash
# Check filesystem, processes, network
docker exec <container> ps aux
docker exec <container> df -h
docker exec <container> cat /etc/resolv.conf
Step 4: Check System Events
# Events for specific container in last 10 minutes
docker events --since 10m --filter container=<container>
# OOM events specifically
docker events --filter event=oom --since 1h
# All die events
docker events --filter event=die --since 1h
Step 5: Resource Usage
# Live resource stats
docker stats <container>
# Single snapshot
docker stats --no-stream <container>
# System-wide disk usage
docker system df -v
Runtime Error Diagnostic Table
Container Exits Immediately (Exit Code 0 or 1)
Symptom
Cause
Fix
Container exits with code 0 instantly
Main process runs in background (daemonizes)
ALWAYS run the process in foreground mode. For nginx: CMD ["nginx", "-g", "daemon off;"]
Container exits with code 0 instantly
CMD is a shell command that completes
Use a long-running process. For shell scripts: end with exec or tail -f /dev/null for debugging
