Why a detached Docker container stops

docker run -d starts a container in detached mode. It does not keep a finished program alive, nor does it set a timer that automatically stops the container. When the main process exits, the container stops unless a restart policy starts it again.

Compare a service with a completed command

docker run -d --name web-example nginx:stable
docker run -d --name completed-example ubuntu:24.04 echo hello
docker ps -a

The Nginx image runs its server in the foreground. The second command prints a message and finishes, so an exit code of zero is expected. Detached mode does not change either program's behavior. A clean exit can still be an operational problem if you expected a long-running service.

A service launched by a wrapper that backgrounds it and then exits may stop immediately. Keep the intended service in the foreground, and use exec in a shell wrapper when appropriate so shutdown signals reach it correctly.

Keep a temporary debugging container available

docker run -dit --name shell-lab ubuntu:24.04 bash
docker run -d --name sleep-lab ubuntu:24.04 sleep infinity

These are alternative debugging patterns. An interactive shell with open input can wait for commands, while this image's sleep infinity stays alive until stopped. tail -f /dev/null is another common placeholder, but availability and behavior depend on the image. A placeholder is not a replacement for supervising the real application or checking its health.

Stop gracefully when possible

docker stop --timeout 60 web-example
docker kill web-example

The commands illustrate different actions, not a required sequence. Stop sends the configured stop signal, normally SIGTERM, waits for the applicable timeout, and then uses SIGKILL if necessary. Defaults differ by platform and can be overridden; Linux commonly defaults to ten seconds. docker kill defaults to SIGKILL, although another signal can be requested.

A shutdown request only gives the application an opportunity to clean up. Correct signal handling, deadlines, and storage behavior still determine whether that succeeds.

Decide whether to restart

docker run -d --name managed-web \
  --restart unless-stopped nginx:stable

unless-stopped restarts eligible containers after exits and daemon restarts, while respecting a manually stopped container. It is not a readiness check or a repair for an invalid configuration. Repeated immediate exits need investigation, even when the restart policy masks them with another attempt.

Stopping preserves the container's writable layer. docker start NAME launches its configured main process again; it does not resume the old process's memory. Removing the container deletes its writable layer, while mounted data follows its own lifecycle. An automatically removed container cannot later be started.

Inspect exit evidence

docker inspect --format '{{json .State}}' completed-example
docker logs completed-example

Exit code 137 commonly indicates termination by SIGKILL, but it is not sufficient proof of an out-of-memory kill. Check OOMKilled, runtime events, host evidence, resource limits, and the application's own output. Likewise, zero means the process reported success, not that a service met its availability requirements.

Configure Guance container log collection before a short-lived container disappears. Correlate its last messages with its inspected exit state; missing application errors do not exclude host or runtime failures.

See Docker run, Docker stop, and restart policies.