Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

docker stop hangs, or the container will not stop or stays down

Errordocker stop takes about 10 seconds every time

Short answer

docker stop sends SIGTERM to the main process and waits 10 seconds before SIGKILL. A container that always takes the full ten seconds has a main process that never receives or never handles SIGTERM. Use exec-form CMD, add --init, or set the right stop signal.

  • Applies to Docker Engine 27, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check what the container runs as its main process and how long a stop takes.

    docker inspect --format '{{.Config.Cmd}} {{.Config.Entrypoint}} {{.Config.StopSignal}}' <container>
    time docker stop <container>
  2. 2Match what you see, then jump to its fix

    1. 1The command in docker inspect is written as /bin/sh -c ...Shell-form CMD or ENTRYPOINT hides the app from the signalFix
    2. 2docker stop always takes the full timeout, and the app logs nothing at shutdownThe app ignores SIGTERM or needs more time to shut downFix
    3. 3docker kill returns the name, but docker ps still shows UpYou sent a signal that does not end the processFix
    4. 4It is back up after the Docker daemon restartsThe container is restarted by its restart policyFix

What does the error look like?

  • docker stop takes about 10 seconds every time
  • docker kill sends a signal and the container keeps running

Cause 1 of 4

Shell-form CMD or ENTRYPOINT hides the app from the signal

1Check

Shell form runs your program as a child of /bin/sh -c. The shell does not pass signals on, so your program never sees SIGTERM and Docker waits for the timeout.

docker inspect --format '{{json .Config.Cmd}}' <container>

2Fix

Write CMD and ENTRYPOINT in exec form, a JSON array, so the program is PID 1. In a start script, finish with exec so the shell replaces itself.

# Dockerfile
CMD ["node", "server.js"]

# entrypoint.sh
exec node server.js

3Verify

Rebuild, start, and time the stop.

docker build -t my-app . && docker run -d --name my-app my-app
time docker stop my-app

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 4

The app ignores SIGTERM or needs more time to shut down

1Check

By default the main process gets SIGTERM, then SIGKILL after 10 seconds on Linux. If the app does not react to SIGTERM, Docker waits out the timeout. An app that needs longer than 10 seconds to close connections and flush data hits the same wall.

docker inspect --format '{{.Config.StopSignal}}' <container>

2Fix

Run with --init, which makes an init process PID 1 and forwards signals. Give the container a longer grace period with --stop-timeout, or set the signal the app does handle.

docker run -d --init --stop-timeout 30 --name my-app my-app
# or in the Dockerfile
# STOPSIGNAL SIGINT

3Verify

docker stop returns well inside the grace period.

time docker stop my-app

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 4

You sent a signal that does not end the process

1Check

docker kill sends SIGKILL by default. A different signal given with --signal may not terminate the main process; SIGHUP often leaves it running.

docker ps --filter name=<container>

2Fix

Use plain docker kill, or docker stop with a longer timeout, instead of a custom signal.

docker kill <container>

3Verify

The container is no longer listed as running.

docker ps -a --filter name=<container>

Confirmed by docs.docker.com

Did this fix it?

Cause 4 of 4

The container is restarted by its restart policy

1Check

A container you stopped by hand ignores always until the daemon restarts or you start it again. With unless-stopped, a hand-stopped container stays down even after a daemon restart.

docker inspect --format '{{.HostConfig.RestartPolicy.Name}}' <container>

2Fix

Change the policy so a deliberate stop is kept.

docker update --restart unless-stopped <container>

3Verify

Stop the container and restart the Docker service. It stays down.

docker ps -a --filter name=<container>

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Write CMD and ENTRYPOINT in exec form.
  • Handle SIGTERM in the app: stop accepting work, flush, then exit.
  • Add --init for images that start several processes, so an init process forwards signals.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.