Docker · tool · fg-0257

depends_on starts the app before the database accepts connections, so first boot fails

ECONNREFUSED or 'the database system is starting up' on first docker compose up, gone after a restart

Verified 2026-10-15 · Confirmed by 0 builders · Trust 50/100

Cause

The short depends_on form waits only until the dependency container is running, not until the process inside it is ready.

Fix

Give the dependency a healthcheck and use the long depends_on form with condition service_healthy.

Apply

services:
  db:
    image: postgres:17
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 2s
      retries: 30
  app:
    depends_on:
      db:
        condition: service_healthy

Affects: Docker Compose v2, as of October 2026

Sources

https://docs.docker.com/compose/how-tos/startup-order/

Have your agent know this before it fails

claude mcp add --transport http footgun https://getfootgun.com/api/mcp