Introduction

depends_on with condition: service_healthy helps startup ordering, but it only works if the dependency has a meaningful health check and the stack actually treats that health result as real readiness. Many Compose setups still start the dependent service too early because the health probe passes before the dependency is truly usable or because the dependency never had a proper health check in the first place.

Symptoms

  • An application starts before its database or cache is truly ready
  • Compose shows a dependency as healthy, but connection attempts still fail
  • A stack works intermittently depending on machine speed and startup timing
  • Operators expect strict orchestration behavior that Compose does not fully provide

Common Causes

  • The dependency’s health check is missing or too shallow
  • The health probe tests process existence instead of real readiness
  • start_period and retries are too short for the actual startup time
  • The application still needs its own retry or wait logic even when Compose gates startup

Step-by-Step Fix

  1. 1.Inspect the dependency’s health status
  2. 2.Confirm the container really has a health check and that the last probe results match reality.
bash
docker compose ps
docker inspect my-db
  1. 1.Make the health check test real readiness
  2. 2.A database should report healthy only when it is accepting connections, not just when the process exists.
yaml
healthcheck:
  test: ["CMD-SHELL", "pg_isready -U postgres"]
  interval: 5s
  timeout: 5s
  retries: 5
  start_period: 30s
  1. 1.Retain application-side retry logic for critical dependencies
  2. 2.Compose startup ordering reduces early failures, but it should not be the only readiness guard in a production-grade application.
  3. 3.Use explicit wait scripts when necessary
  4. 4.For complex dependencies, an application entrypoint wait script may still be the most reliable final guard.

Prevention

  • Write health checks that reflect the dependency’s true usable state
  • Give slow services enough start_period and retry budget
  • Treat Compose ordering as an aid, not a full orchestration contract
  • Keep dependency retry logic inside the application or entrypoint for resilience