P1
Docker CrashLoopBackOff — Interactive Troubleshooting Checklist
Diagnose and fix a Docker container that keeps restarting or exiting immediately. Covers logs, OOM detection, interactive debugging, volume permissions, and configuration errors.
15 min7 steps
Progress: 0/7 steps
0%
See the current state and restart count of the container.
docker ps -a --filter name=CONTAINER_NAME
Expected: STATUS column shows 'Restarting' or 'Exited (N)' with exit code. Exit code 1=app error, 137=OOM killed, 139=segfault.
Get the most recent logs from the container.
docker logs --tail 100 CONTAINER_NAME
Expected: Application error messages. Look for config errors, missing environment variables, connection failures, or permission issues.
Get detailed configuration to check env vars, mounts, and networking.
docker inspect CONTAINER_NAME | jq '.[0] | {State, Config: {Env: .Config.Env, Cmd: .Config.Cmd}, HostConfig: {Binds: .HostConfig.Binds, PortBindings: .HostConfig.PortBindings}}'Expected: Container state, environment variables, mounted volumes, and port bindings.
Verify if the container was killed due to memory limits.
docker inspect CONTAINER_NAME | jq '.[0].State.OOMKilled'
Expected: 'true' means the container exceeded its memory limit. Increase memory limit in docker-compose.yml.
Start the container with an interactive shell to debug inside.
docker run --rm -it --entrypoint /bin/sh IMAGE_NAME
Expected: Shell inside the container. Check if config files exist, try running the app manually.
Use /bin/sh for alpine-based images, /bin/bash for debian/ubuntu-based.
Ensure mounted volumes exist and have correct permissions.
docker inspect CONTAINER_NAME | jq '.[0].Mounts' && ls -la /path/to/host/volume/
Expected: Verify mount paths exist on the host and the container user has read/write access.
After fixing the issue, recreate the container.
docker compose up -d CONTAINER_NAME && sleep 5 && docker ps --filter name=CONTAINER_NAME
Expected: Container should show status 'Up X seconds' without '(Restarting)'.