Docker Compose depends_on condition not working: why your container starts before Postgres is ready and how to fix it

The container that calls itself “waiting for the database” is not waiting for the database — depends_on with a healthcheck condition only orders container creation and start, and if your service still crashes on boot, the healthcheck is either missing, misconfigured, or being ignored because you are on a Compose version that never supported the condition you wrote.

The one-liner that actually gates startup:

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

Now here is what it actually does, and the three ways it silently fails.

The myth is that depends_on waits for the database to accept connections

Plain depends_on does not wait for anything to be ready — it only controls start order, and even that guarantee is weaker than most people think. The Docker docs for Compose startup order (current as of 2026) state plainly that Compose starts containers in dependency order but does not wait for them to be “ready” — that is what the condition field is for, and it only works when a healthcheck exists on the dependency.

So the assumption “my app starts after Postgres” is true in the sense that the db container has been created. It is false in the sense that matters: Postgres has finished initdb, opened its socket, and is accepting TCP connections. On a cold volume, initdb alone routinely takes several seconds; the container is running the whole time, so depends_on is satisfied immediately.

This is the failure mode that costs people hours: the app container exits with connection refused or could not connect to server, you add depends_on, it still fails, and you conclude Compose is broken. Compose is not broken. You told it to start in order, not to wait for readiness.

condition: service_healthy does nothing if the dependency has no healthcheck

If the service you depend on defines no healthcheck, Compose has no state to wait for, and depending on your version it either errors at parse time or treats the container as healthy the moment it is running. The fix is to define the healthcheck on the dependency, not on the app.

For Postgres, use pg_isready rather than a TCP check. A raw TCP connect succeeds as soon as the port is bound, which can be before the server is ready to serve queries. pg_isready asks the server itself:

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

Two details that trip people up. First, $${POSTGRES_USER} — the double dollar escapes the variable so the container’s shell expands it at runtime, not Compose at parse time. Single $ will substitute an empty string from your host environment and pg_isready will fail with a confusing “no such user” or connect as the wrong role. Second, start_period is the grace window during which a failing check does not count against retries — without it, a slow first initdb burns your retries before the server is even up.

For other services the same pattern applies with the right probe: redis-cli ping for Redis, curl -f http://localhost:8080/health for an HTTP service, mysqladmin ping for MySQL.

The condition you wrote may be silently unsupported by your Compose version

condition: service_healthy under depends_on is a long-form, Compose-spec feature — it is not part of the legacy v2 file format, and older Compose binaries reject or ignore it. Check what you are actually running before you debug anything else:

docker compose version
# Docker Compose version v2.29.7  (example — confirm your own)

docker compose config
# prints the resolved, merged config Compose will actually use

docker compose config is the underrated debugging step: it renders the file after interpolation and merge, so if your condition or $${...} escaping is wrong, you see it here rather than at runtime. If the long-form depends_on is missing from that output, your file format or Compose version is the problem, not Postgres.

One more environment fact worth naming: Compose v2 ships as a Docker CLI plugin, and its behaviour is version-specific. The Docker documentation for the Compose depends_on reference (2026) is the authoritative source for which condition values are valid — service_started, service_healthy, and service_completed_successfully — and anything else is a typo that may be accepted silently depending on version.

A healthcheck that passes does not mean your app is safe to start

Even with a correct service_healthy gate, the app can still fail, because a healthy dependency is not the same as a migrated, seeded, or fully-initialised one. Postgres can be pg_isready-healthy while your app’s first migration is still racing the same database from another container. This is the second failure mode that costs hours: the gate works, the app starts, and it dies on a schema that does not exist yet.

The robust pattern is belt and braces — gate on health and make the app retry:

services:
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: app
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 5s
      timeout: 5s
      retries: 10
      start_period: 10s
  app:
    build: .
    command: sh -c "./wait-for-db.sh && ./start.sh"
    depends_on:
      db:
        condition: service_healthy
    restart: on-failure

restart: on-failure is the safety net for the case the healthcheck cannot cover: a transient connection failure during your own startup logic. It is not a substitute for the gate — a crash-looping app with no gate will hammer the database and fill logs — but combined with the gate it turns a hard failure into a retry.

If you want a concrete number for your own stack rather than a guess, measure the time from docker compose up to pg_isready succeeding on a cold volume:

time docker compose up -d db
docker compose exec db pg_isready -U app -d app

Set start_period above that measured value. Do not copy someone else’s 10s and hope.

Do not use sleep or a connection loop in place of a healthcheck

command: sh -c "sleep 10 && ./start.sh" is the cargo-cult fix and it fails in both directions: too short on a cold CI runner, needlessly slow on a warm laptop. Do this instead — put the readiness logic on the dependency as a healthcheck, gate with condition: service_healthy, and keep a bounded retry in the app for the schema-race case the healthcheck cannot see.

The failure mode to watch for: a healthcheck that passes for the wrong reason. A curl -f against a port that is bound but not serving returns success on some servers, and a TCP check succeeds before the database is ready. Verify your probe fails when it should by stopping the dependency and confirming the app does not start — if it starts anyway, your gate is decorative.

Related Articles

For a ready-to-use framework, see our VRAM comparison of the best open-source AI models to self-host.

Similar Posts

Leave a Reply

Your email address will not be published. Required fields are marked *