docker compose depends_on does not wait for your database: fix "connection refused" on startup with healthchecks

api-1  | Error: connect ECONNREFUSED 172.18.0.2:5432
api-1 exited with code 1
db-1   | LOG:  database system is ready to accept connections

The app died one line before Postgres was ready. Run docker compose up again and it works. Your compose file says depends_on: [db], so what happened?

depends_on waits for "running", not "ready"

The list form of depends_on means condition: service_started. Compose starts db, sees the container running, starts your app. Meanwhile Postgres is still running initdb and your init scripts. The Docker docs say it directly: Compose waits for running, not ready.

The trap: service_healthy with no healthcheck

So you switch to condition: service_healthy. But the official postgres, mysql, mongo, redis and rabbitmq images define no HEALTHCHECK (on purpose). Without a healthcheck: in compose, startup fails with "has no healthcheck configured" or "container is unhealthy" instead of waiting.

The fix

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

$$ stops Compose interpolating the variable on your host. start_period keeps a slow first boot from burning your retries. And keep a connection retry in the app anyway: databases restart in production too.

Flag it in the editor

I built ReadyWait, a free VS Code extension that checks every compose file in the workspace:

• RW001 short-form depends_on / service_started on postgres, mysql, redis, kafka, rabbitmq and other slow services
• RW002 service_healthy on a service with no (or a disabled) healthcheck
• RW003 no start_period, or timeout longer than interval
• RW004 service_completed_successfully on a restart: always service

One-click fixes convert depends_on to long form and insert pg_isready, mysqladmin ping, redis-cli ping, rabbitmq-diagnostics and similar probes where the tool ships in the official image. Override files and local Dockerfile HEALTHCHECKs count. Fully static: no network, no telemetry, no docker calls. It cannot see a HEALTHCHECK baked into a registry image, and it does not follow YAML anchors or include:.

code --install-extension jaytankdev.readywait

Source (MIT): github.com/jay-tank/readywait

Full write-up (why startup races happen, every healthcheck command, limitations, FAQ): docker compose depends_on does not wait for your database