Maaz Zindani

Loading the index…

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

A Compose service does not come back after it crashes or the server reboots

ErrorExited (0) in the STATUS column of docker ps -a

Short answer

Compose restarts a container only if the service has a restart: value, and each value has limits. The default is no. on-failure ignores a clean exit and does not survive a daemon restart. Nothing restarts a container that you stopped by hand or that dies in under ten seconds.

  • Applies to Docker Engine 28, Docker Compose 2.x
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask Docker for the container state and how many restarts it has done. Together with the restart line in the Compose file, this tells you which cause below applies.

    grep -n "restart" compose.yaml
    docker ps -a
    docker container inspect --format '{{.State.Status}} restarts={{.RestartCount}}' my-app
  2. 2Match what you see, then jump to its fix

    1. 1grep finds no restart: line for the service, and the container stays Exited after a crashThe service has no restart policyFix
    2. 2Exited (0) in docker ps -a, with restart: on-failure in the fileon-failure does not restart a container that exited with code 0Fix
    3. 3The container shows Exited seconds after start and RestartCount stays 0The container crashes before it has run for ten secondsFix
    4. 4You ran docker stop or docker compose stop before the reboot, and the container stayed down afterwardsThe container was stopped by handFix

What does the error look like?

  • Exited (0) in the STATUS column of docker ps -a
  • Exited (137) in the STATUS column of docker ps -a

Cause 1 of 4

The service has no restart policy

1Check

The default policy is no. Compose then does not restart the container under any circumstances.

grep -n "restart" compose.yaml

2Fix

Set a policy on the service. unless-stopped is the usual choice for servers, on-failure:5 gives up after five tries.

services:
  api:
    image: my-app:latest
    restart: unless-stopped

3Verify

Recreate the container so the new policy applies, then confirm it is running.

docker compose up -d
docker compose ps

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 4

on-failure does not restart a container that exited with code 0

1Check

on-failure restarts only after a non-zero exit code. A program that ends normally, for example a script that finishes or a server that handles a shutdown signal and returns 0, is left stopped. on-failure also does not restart containers when the daemon restarts.

docker ps -a --filter name=my-app

2Fix

If the service must always run, use unless-stopped or always. Keep on-failure for jobs that should be retried only when they fail.

services:
  worker:
    image: my-worker:latest
    restart: unless-stopped

3Verify

Stop the process inside the container the hard way and watch the restart count rise.

docker compose up -d
docker container inspect --format '{{.RestartCount}}' my-worker

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 4

The container crashes before it has run for ten seconds

1Check

A policy applies only after the container has been up for at least 10 seconds and Docker is watching it. This stops a container that can never start from looping. The real fault is then inside the app, so read its log.

docker compose logs --tail 50 api

2Fix

Fix the startup error the log shows (missing variable, wrong database host, bad command). Do not raise the policy limits: the policy cannot help a container that never starts.

docker compose up -d
docker compose logs -f api

3Verify

The container stays Up past ten seconds.

docker compose ps

Confirmed by docs.docker.com

Did this fix it?

Cause 4 of 4

The container was stopped by hand

1Check

A manual stop overrides the policy until the daemon restarts or you start the container again. With unless-stopped, a container you stopped by hand stays stopped even after the daemon comes back; with always it returns only when the daemon restarts.

docker ps -a

2Fix

Start it again with Compose. Leave it stopped on purpose only when you mean to.

docker compose up -d

3Verify

The service shows as running.

docker compose ps

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Put restart: unless-stopped on every long-running service in the Compose file and review it in code review.
  • Make jobs that end by design (migrations, one-off tasks) a separate service without a restart policy, or use on-failure:3.
  • Do not run systemd or another supervisor to restart containers that already have a Docker restart policy; Docker warns that the two conflict.

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.