How to debug a crashing Docker container

Identify why a Docker container crashes on startup or exits immediately using docker logs, docker exec, and interactive docker run techniques.

Step-by-Step: Debug a Crashing Docker Container

1. Check Container Logs with docker logs

docker logs container-name

Docker logs display the container's standard output and standard error. The last lines before the crash typically reveal the error message.

2. Check the Container Exit Code

docker inspect container-name --format='{{.State.ExitCode}}'

Exit code 0 means normal shutdown. Exit code 1 means the application crashed. Exit code 137 means the container was killed (OOM or docker kill). Exit code 139 means a segmentation fault.

3. Run the Container Interactively

docker run -it --entrypoint /bin/sh image-name

The -it flags attach a terminal. The --entrypoint /bin/sh overrides the default command, dropping into a shell inside the container for manual debugging.

4. Exec into a Running Container

If the container stays running long enough, exec into it:

docker exec -it container-name /bin/bash

Common Issues

Container exits immediately with no logs— The container's main process is not running in the foreground. Docker containers exit when PID 1 exits. Ensure the main process runs with -d or without backgrounding (no &).