Docker Container Exits Immediately: How to Debug It

You run docker run and the container vanishes immediately — docker ps shows nothing. Frustrating, but containers don't exit at random. There's always a reason in the logs, and a short checklist finds it fast.

First rule: a container lives as long as its main process

A container runs exactly one main process and stays alive only while that process does. If the process finishes or crashes, the container stops. So "exits immediately" means: the main command ended right away. Your job is to find out why.

Step 1: Read the logs

The exited container is still around. List it (including stopped ones) and read its output:

docker ps -a            # find the container ID
docker logs <id>        # see what it printed before dying

Nine times out of ten the error message is sitting right there — a missing file, a bad config value, a stack trace.

Step 2: Check the exit code

docker ps -a shows how it exited. Exited (0) means the process finished successfully (it simply had nothing long-running to do). A non-zero code like Exited (1) means it crashed — combine that with the logs.

Step 3: Look inside by overriding the command

If the logs are empty, start the container with an interactive shell instead of its normal command, then poke around:

docker run -it --entrypoint sh <image>

Now you can check whether files exist, run the start command by hand, and watch it fail in real time.

A container that "does nothing" usually isn't broken — its main process just had nothing to keep it running. A crash, by contrast, leaves evidence in the logs.

Common causes

• The command finished (a script that runs once and exits).
• A crash on startup — missing env var, bad config, file not found.
• The app needs to run in the foreground but was backgrounded, so the container thinks it's done.

The takeaway

Don't guess. docker ps -a, then docker logs, then if needed shell in with an overridden entrypoint. The container always tells you why it left — you just have to read it.