Docker Compose depends_on Not Waiting: Add a Healthcheck

Why depends_on can look broken#

The short syntax is useful for ordering:

1
services:
2
  web:
3
    image: example/web
4
    depends_on:
5
      - db
6

7
  db:
8
    image: postgres:18

It tells Compose that db is a dependency of web. It does not describe when the database can accept connections. A container can be running while PostgreSQL is still initializing, migrations are pending, or an application-specific readiness condition has not been met.

The Compose startup-order documentation defines three useful dependency conditions:

• service_started: the dependency has started.
• service_healthy: the dependency’s healthcheck has passed.
• service_completed_successfully: the dependency ran to completion with exit code zero.

Use the condition that matches the contract. Do not use service_healthy without defining what healthy means.

Add a healthcheck that tests readiness#

For PostgreSQL, a minimal readiness gate can look like this:

1
services:
2
  web:
3
    build: .
4
    depends_on:
5
      db:
6
        condition: service_healthy
7
        restart: true
8

9
  db:
10
    image: postgres:18
11
    environment:
12
      POSTGRES_USER: app
13
      POSTGRES_PASSWORD: example
14
      POSTGRES_DB: app
15
    healthcheck:
16
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
17
      interval: 10s
18
      timeout: 10s
19
      retries: 5
20
      start_period: 30s

The official example uses pg_isready and escapes the dollar signs as $${...} so Compose passes the variable expression into the container instead of interpolating it too early. The command, credentials, and database name must match the image and application you actually run.

For Redis, an HTTP service, or a custom worker, replace the probe with a command that is available in that image and checks the service’s useful boundary. A TCP port being open may still be weaker than a protocol-level check.

Choose the right dependency condition#

1
services:
2
  web:
3
    build: .
4
    depends_on:
5
      migrate:
6
        condition: service_completed_successfully
7

8
  migrate:
9
    build: .
10
    command: ./bin/migrate
11
    restart: "no"

Debug the rendered model, then the health state#

Check the Compose model before debugging the application:

1
docker compose config --services
2
docker compose config --quiet
3
docker compose up -d db
4
docker compose ps

If the database is not healthy, inspect its logs and health state instead of restarting the web container repeatedly:

1
docker compose logs db
2
docker inspect --format '{{json .State.Health}}' PROJECT-db-1

The exact container name varies by project name and Compose version. docker compose ps gives you the name to inspect. Also check these common mistakes:

• The healthcheck binary is not installed in the image.
• The probe uses localhost when the real client connects over the Compose service name.
• The port or credentials in the probe do not match the container environment.
• start_period is shorter than the dependency’s normal initialization time.
• The dependency becomes healthy, then loses its connection later; a startup gate does not replace application retries.

If the service is inside a profile, activate the same profile while rendering and starting the model. The existing Compose profile troubleshooting guide covers profile activation; this article covers readiness after the service is selected.

FAQ#