Maaz Zindani

Loading the index…

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

Docker Compose starts container B before container A is healthy

Errorhealth status: starting

Short answer

Compose does not wait for a container to be ready, only for it to be running. To make service B wait for A, give A a working healthcheck and put depends_on with condition: service_healthy on B. If A stays unhealthy, the healthcheck command itself is wrong, or its timing is too tight.

  • Applies to Docker Compose 2.40, Docker Engine 28
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    See what Docker thinks of the dependency's health, and read the output of the last checks.

    docker compose ps
    docker inspect --format '{{json .State.Health}}' $(docker compose ps -q db)
  2. 2Match what you see, then jump to its fix

    1. 1The app logs a connection error in the first seconds while the database container shows as runningdepends_on is written in short form, so Compose only waits for startFix
    2. 2State.Health shows failing checks with an exit code and output such as 'curl: not found' or 'connection refused'The healthcheck command fails inside the imageFix
    3. 3The dependency does become healthy later, but Compose already stopped with 'is unhealthy'The timing is too tight for a slow startFix

What does the error look like?

  • health status: starting
  • health status: unhealthy

Cause 1 of 3

depends_on is written in short form, so Compose only waits for start

1Check

The short form (a list of service names) is the same as service_started. Compose by default does not wait for a container to be ready, only until it is running.

docker compose config | grep -A4 depends_on

2Fix

Use the long form with condition: service_healthy, and give the dependency a healthcheck.

services:
  web:
    build: .
    depends_on:
      db:
        condition: service_healthy
  db:
    image: postgres:18
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 10s
      retries: 5
      start_period: 30s
      timeout: 10s

3Verify

Bring the stack up and see web created only after db shows healthy.

docker compose up -d && docker compose ps

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 3

The healthcheck command fails inside the image

1Check

A healthcheck passes only when the command exits 0 (1 means unhealthy, 2 is reserved). The command runs inside the container, so a tool the image does not have, or a URL the app does not serve, keeps it unhealthy. Output of the check is kept in the health status.

docker inspect --format '{{range .State.Health.Log}}{{.ExitCode}} {{.Output}}{{end}}' $(docker compose ps -q db)

2Fix

Use a command that exists in the image and tests the real thing (pg_isready for Postgres, a client ping for Redis, curl or wget only if installed). Use CMD-SHELL when you need shell variables.

healthcheck:
  test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]

3Verify

Run the same command by hand inside the container and check the exit code is 0.

docker compose exec db sh -c 'pg_isready -U $POSTGRES_USER -d $POSTGRES_DB; echo exit=$?'

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 3

The timing is too tight for a slow start

1Check

A container turns unhealthy after retries (default 3) failed checks in a row. Failures inside start_period do not count, and the default start_period is 0s.

docker compose config | grep -B2 -A8 healthcheck

2Fix

Give the container a start_period that covers a normal start, and raise retries or interval if checks are slow.

healthcheck:
  test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
  interval: 10s
  timeout: 10s
  retries: 5
  start_period: 30s

3Verify

Start from empty volumes once to see the slowest start pass.

docker compose down -v && docker compose up -d && docker compose ps

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Add a healthcheck to every service another service depends on, and use service_healthy for it.
  • Run the healthcheck command by hand in the container before trusting it.
  • Still make the app retry its connection; a database can restart after startup.
  • Use restart: true under depends_on when the app should restart after a Compose-managed dependency restart.

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.