Compose depends_on service_healthy and Docker HEALTHCHECK: startup ordering versus application readiness

Direct answer

depends_on with condition: service_healthy gates container creation on the dependency's Docker HEALTHCHECK reporting success. It does not guarantee the application inside that container is ready to accept the dependent service's traffic. Treat it as a startup ordering signal, not an application readiness contract.

Confirmed behavior versus likely explanation

Confirmed: the Compose Specification used by modern docker compose supports service_healthy and service_completed_successfully. Compose file format 3.x dropped depends_on conditions; if an older tool interprets your file, the condition may be silently normalized to a plain dependency. Confirmed: HEALTHCHECK timing flags—start-period, interval, timeout, and retries—determine when a container transitions to healthy, and those values differ across images and hosts.

Likely explanation: the readiness gap is expected, not a bug. The specification does not define a readiness contract for service_healthy; it reflects only the probe outcome. A health probe validates a container-level condition (for example, a process exists or a port is listening). It does not validate that caches are warm, schemas are loaded, or connection pools are initialized. The dependent service can start while the dependency is still warming up.

Steps for this case

1. Verify the schema is honored. Run docker compose config and confirm the depends_on block still contains condition: service_healthy. If it is missing, your file was normalized by an incompatible Compose version.
2. Separate ordering from readiness. Use service_healthy to avoid starting the dependent before the dependency container exists. In the dependent service, implement connection retries with backoff for the first requests. This handles the residual gap regardless of probe timing.
3. Optionally tighten the probe. If the dependency exposes a readiness endpoint, point HEALTHCHECK at it (for example, a /ready route that returns 200 only when the application can serve traffic). This makes service_healthy a stronger signal, but it is still a probe result, not a distributed readiness guarantee.

One diagnostic detail that changes the recommendation

Which Compose implementation and schema version are you using? If you are on Compose file format 3.x with a legacy docker-compose binary, the condition may be ignored entirely and the recommendation shifts to upgrading the schema or adding explicit wait logic. If you are on the Compose Specification with docker compose v2+, the condition is enforced and the focus should be on application-level retries.