When a container won't start, crashes, or behaves unexpectedly, a systematic debugging approach gets you to the root cause faster than random troubleshooting. This guide covers the essential techniques.
Step 1 — Check Container Status
docker ps -aShows all containers including stopped ones, with their exit status — an exit code other than 0 indicates the container terminated abnormally.
Step 2 — Check the Exit Code
docker inspect myapp --format='{{.State.ExitCode}}'| Exit Code | Common Meaning |
|---|---|
| 0 | Normal, successful exit |
| 1 | General application error |
| 137 | Killed (often OOM — out of memory) |
| 139 | Segmentation fault |
Step 3 — Check Container Logs
docker logs myappdocker logs --tail 100 -f myappThe first place to look for actual error messages explaining why the application failed.
Step 4 — Check for OOM Kill Specifically
docker inspect myapp --format='{{.State.OOMKilled}}'If true, see How to Set Resource Limits on Docker Containers (CPU/Memory) — either increase the memory limit or investigate why the application needs more than allocated.
Step 5 — Run the Container Interactively for Live Debugging
docker run -it --entrypoint /bin/sh myappOverrides the normal startup command with an interactive shell, letting you explore the container's file system and manually test commands to understand what's actually failing.
Step 6 — Exec Into a Running Container
docker exec -it myapp /bin/shFor a container that starts but behaves incorrectly (rather than crashing immediately), get a shell inside the running container to investigate directly.
Step 7 — Check Environment Variables Are Correctly Set
docker exec myapp envA surprisingly common cause of failures — missing or incorrect environment variables the application depends on; see Docker Compose .env Files and Environment Variables Explained.
Step 8 — Verify Network Connectivity from Within the Container
docker exec myapp ping -c 3 db
docker exec myapp curl -v http://api-service:3000/healthIf the application depends on other services (a database, another container), verify it can actually reach them — see Docker Networking Explained if connectivity issues are suspected.
Step 9 — Check for Port Binding Conflicts
sudo ss -tulnp | grep PORTIf the container fails to start with a port-related error, verify the host port isn't already in use by another process.
Step 10 — Review the Dockerfile/Compose Configuration Itself
Sometimes the issue is in the image build or compose configuration rather than runtime behavior — review recent changes to the Dockerfile or compose file for anything that might explain the new failure.
A Systematic Debugging Checklist
- Check logs first — often immediately reveals the actual error
- Check exit code and OOM status
- Verify environment variables and configuration
- Test connectivity to dependencies if applicable
- Run interactively if logs alone don't explain the issue
Continue Reading
- Docker Compose Troubleshooting: Common Errors & Fixes
- Managing Docker Logs: Viewing, Rotating & Centralizing
- Docker Networking Explained: Bridge, Host & Custom Networks
Browse more articles in Docker & Containers.
