DockerJunior

Compose service starts before its database is ready

depends_on only waits for a container to start. Use a healthcheck and condition: service_healthy so your app starts after the database is ready.

What you see

  • The app container fails to connect to the database on docker compose up, then works if you start it again later

What it means

Compose starts containers in dependency order, but by default it waits only until a dependency is running, not until it is ready. A database needs time after the process starts before it accepts connections.

How to confirm the cause

  1. 1
    Check the dependency's health status
    docker compose ps

    A service with a healthcheck shows its health state.

  2. 2
    Read the app's logs
    docker compose logs web

    Confirm the failure is a connection error at startup and not a bad password.

Causes and fixes

  • depends_on has no condition

    HOW TO TELL
    The compose file lists depends_on: - db only.
    FIX
    Add a healthcheck to the dependency and use condition: service_healthy on the service that needs it.
    services:
      web:
        build: .
        depends_on:
          db:
            condition: service_healthy
            restart: true
      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

How to stop it coming back

  • Make the app retry its first connection with a delay. A healthcheck helps at startup but does not cover a database restart later.
  • Use service_completed_successfully for one-off setup jobs such as migrations.

Keep going

Sources

Docker documentation (docs.docker.com), read 18 Nov 2026 from the official docs repository.

Search

Search cheat sheets and projects