How to Debug a Failing Docker Container

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 -a

Shows 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 CodeCommon Meaning
0Normal, successful exit
1General application error
137Killed (often OOM — out of memory)
139Segmentation fault

Step 3 — Check Container Logs

docker logs myapp
docker logs --tail 100 -f myapp

The 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 myapp

Overrides 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/sh

For 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 env

A 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/health

If 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 PORT

If 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

  1. Check logs first — often immediately reveals the actual error
  2. Check exit code and OOM status
  3. Verify environment variables and configuration
  4. Test connectivity to dependencies if applicable
  5. Run interactively if logs alone don't explain the issue

Continue Reading

Browse more articles in Docker & Containers.

  • debug docker container, docker container crashes, docker exit code, docker logs troubleshooting
  • 0 Korisnici koji smatraju članak korisnim
Je li Vam ovaj odgovor pomogao?

Vezani članci

How to Install Docker Engine on Ubuntu & Debian (Complete Guide)

Docker lets you package applications and their dependencies into lightweight, isolated containers...

How to Install Docker Compose on Ubuntu & Debian

Docker Compose lets you define and run multi-container applications from a single YAML file,...

Deploy Your First Docker Container: A Beginner's Walkthrough

With Docker installed, this hands-on walkthrough covers the core workflow you'll use constantly:...

How to Update Docker and Docker Compose Safely

Keeping Docker Engine and Compose updated brings security fixes, performance improvements, and...

Docker Compose Troubleshooting: Common Errors & Fixes

A reference guide to the Docker and Docker Compose errors you're most likely to encounter, with...