gotchadockerMajor
depends_on does not wait for service readiness, only container start
Viewed 0 times
condition key requires Docker Compose v2
depends_onstartup orderservice_healthyreadinessrace conditionwait-for-it
Error Messages
Connection refusedECONNREFUSEDdial tcp: connect: connection refusedProblem
Compose
depends_on causes services to start in order, but the dependent service starts as soon as the dependency container is running — not when it is ready to accept connections. Apps crash on startup trying to connect to an unready database.Solution
Use
Alternatively, make the app retry connections with exponential backoff instead of failing immediately.
condition: service_healthy with a HEALTHCHECK, or use a wait script like wait-for-it.sh:depends_on:
db:
condition: service_healthyAlternatively, make the app retry connections with exponential backoff instead of failing immediately.
Why
Compose v1
depends_on only controlled start order. The condition field was added to address this gap. Without it, services start in order but race conditions with slow-starting services remain.Gotchas
- condition: service_healthy requires the dependency to have a HEALTHCHECK defined in its image or compose config
- condition: service_started (default) = old behavior, only waits for container to start
- condition: service_completed_successfully is for one-shot services like migrations
- Retry logic in your app code is more resilient than relying solely on depends_on
Code Snippets
Full depends_on chain with healthcheck and migration service
services:
db:
image: postgres:16
healthcheck:
test: ["CMD", "pg_isready", "-U", "postgres"]
interval: 5s
timeout: 3s
retries: 5
start_period: 10s
migrate:
image: myapp
command: python manage.py migrate
depends_on:
db:
condition: service_healthy
app:
image: myapp
depends_on:
migrate:
condition: service_completed_successfully
db:
condition: service_healthyContext
Docker Compose setups where services depend on a database or other slow-starting service
Revisions (0)
No revisions yet.