🚨 Docker Error Guide: 'Container is not running' — Why exec and Restart Fail

Overview

Docker returns this when you try to act on a container — usually docker exec or docker attach — that is not in the running state:

Error response from daemon: Container 3f9a1c8e2b7d is not running

The daemon is telling you the container’s main process (PID 1) has already exited, so there is nothing to exec into. The real problem is not the command you just ran; it is why the container stopped in the first place.

Symptoms

• docker exec -it <id> sh fails immediately with Container ... is not running.
• docker ps does not list the container, but docker ps -a shows it as Exited.
• A container appears to start and then vanishes within seconds.
• Compose reports the service as exited while dependent services fail to connect.

Common Root Causes

• The main process exited — PID 1 finished (a script ran to completion) or crashed, so the container stopped.
• A foreground process backgrounded itself — the entrypoint launched a daemon and returned, so Docker saw the container as done.
• The command failed on startup — a missing config file, bad environment variable, or unreadable dependency caused a non-zero exit.
• Out-of-memory kill — the kernel OOM-killed PID 1; docker inspect shows OOMKilled: true.
• Wrong entrypoint/command — the image’s CMD was overridden with something that exits immediately (e.g. running a one-shot command).
• Attempting exec against a stopped or restarting container — the container is mid-restart or already exited when the exec is issued.

Diagnostic Workflow

Confirm the container’s actual state and exit code:

docker ps -a --filter "id=3f9a1c8e2b7d"
docker inspect --format '{{.State.Status}} exit={{.State.ExitCode}} oom={{.State.OOMKilled}}' 3f9a1c8e2b7d

Read the logs — the exit reason is almost always here:

docker logs 3f9a1c8e2b7d
docker logs --tail 50 --timestamps 3f9a1c8e2b7d

Check what PID 1 was actually configured to run:

docker inspect --format 'entrypoint={{.Config.Entrypoint}} cmd={{.Config.Cmd}}' 3f9a1c8e2b7d

If the container exits too fast to debug, override the entrypoint to get an interactive shell without starting the failing process:

docker run -it --rm --entrypoint sh myapp:1.4.2

From inside, run the intended command manually and watch the error, then check the daemon log for kills:

journalctl -u docker --since '15 min ago' | grep -i 'oom\|kill'

Example Root Cause Analysis

A developer reported that docker exec -it web sh kept returning Container ... is not running, even though docker run had just been issued. docker ps -a showed the container Exited (0) two seconds after start.

Logs told the story:

docker logs web
# nginx: [emerg] open() "/etc/nginx/conf.d/site.conf" failed (2: No such file)

The image expected a config mounted at runtime, but the -v flag had a typo, so nginx failed its config test and exited immediately. Inspecting confirmed a clean stop, not an OOM kill:

docker inspect --format '{{.State.ExitCode}} {{.State.OOMKilled}}' web
# 1 false

Fixing the volume path so the config was present kept nginx in the foreground, the container stayed Up, and docker exec worked. The lesson: is not running is a symptom — the exit code and logs are the diagnosis.

Prevention Best Practices

• Run a single long-lived foreground process as PID 1; never background the main service inside the entrypoint.
• Add a HEALTHCHECK so unhealthy containers are visible before you try to exec into them.
• Set memory limits deliberately and monitor for OOMKilled: true so silent kills do not surprise you.
• Fail fast and log clearly on missing config or env vars so docker logs explains the exit.
• Validate the image’s entrypoint and command with the Dockerfile validator and standardize runtime patterns from the Docker stack guide.

Quick Command Reference

docker ps -a --filter "id=<id>"
docker logs --tail 50 --timestamps <id>
docker inspect --format '{{.State.Status}} {{.State.ExitCode}} {{.State.OOMKilled}}' <id>
docker inspect --format '{{.Config.Entrypoint}} {{.Config.Cmd}}' <id>
docker run -it --rm --entrypoint sh myapp:1.4.2      # debug without the failing entrypoint
journalctl -u docker --since '15 min ago' | grep -i oom

Conclusion

Container is not running never means “the exec command is wrong” — it means PID 1 has already exited. Look at docker ps -a for the exit code, read docker logs for the reason, and confirm whether the kernel OOM-killed it. The durable fix is to keep a single foreground process alive as PID 1 and to make startup failures loud, so a stopped container tells you exactly why it stopped.