Docker Compose "dependency failed to start: ... is unhealthy" in CI
Compose held a service back behind depends_on: { condition: service_healthy }, and the dependency never became healthy. The dependent service is aborted with "dependency ... is unhealthy" because its prerequisite failed its healthcheck.
What this error means
A docker compose up aborts with dependency failed to start: container <dep> is unhealthy, and the dependent service never starts. The dependency’s own healthcheck is failing or timing out.
service "api" depends_on:
db:
condition: service_healthy
# up fails with:
dependency failed to start: container project-db-1 is unhealthyCommon causes
The dependency’s healthcheck never passes
The depended-on service has a healthcheck that fails - wrong probe command, app not ready in time, or no start-period - so it never reaches healthy and Compose gives up on the dependent.
condition: service_healthy without a healthcheck
Using condition: service_healthy against a service that defines no healthcheck (or only inherits a NONE one) means the condition can never be satisfied.
Timeout too short for the dependency to start
A slow dependency (database migrations, JIT warmup) that exceeds the healthcheck retries/start-period is marked unhealthy before it is actually ready.
How to fix it
Give the dependency a correct healthcheck and start-period
Define a real healthcheck on the depended-on service with enough start-period.
services:
db:
image: postgres:16
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 5s
timeout: 5s
retries: 10
start_period: 30s
api:
depends_on:
db:
condition: service_healthyInspect why the dependency is unhealthy
Read the dependency’s health log to see the failing probe.
docker inspect --format '{{json .State.Health}}' project-db-1
docker compose logs dbHow to prevent it
- Define a real healthcheck on any service others wait on with
service_healthy. - Set a
start_periodlong enough for the dependency’s real startup. - Use
service_startedwhen you only need the dependency launched, not healthy.