Docker Compose "dependency failed to start: container is unhealthy" in CI

A service is gated on a dependency being healthy (depends_on: condition: service_healthy), but that dependency’s healthcheck never passed in time. Compose aborts the stack because the prerequisite is unhealthy.

What this error means

A docker compose up fails with dependency failed to start: container <dep> is unhealthy. The dependent service never starts because Compose waited for the dependency’s healthcheck and it stayed unhealthy.

docker compose output

dependency failed to start: container my-stack-db-1 is unhealthy
# db has a healthcheck; it never reported healthy within retries x interval

Common causes

The dependency is genuinely failing to become ready

The database/service crashes, misconfigures, or takes longer than the healthcheck allows, so it never reports healthy and the gate fails.

The healthcheck itself is wrong

A healthcheck command that always fails (wrong tool, wrong port, wrong credentials) marks a working service unhealthy regardless of its real state.

Timeout too short for cold start in CI

On a cold CI runner the dependency may need more time; too few retries or too short an interval/start_period trips the gate before the service is up.

How to fix it

Inspect why the dependency is unhealthy

Look at the dependency’s logs and its healthcheck result.

Terminal

docker compose logs db
docker inspect --format '{{json .State.Health}}' my-stack-db-1

Fix or loosen the healthcheck

Correct the probe and give cold starts enough time with a start period and retries.

docker-compose.yml

services:
  db:
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 10
      start_period: 30s

How to prevent it

Write healthchecks that probe real readiness (e.g. pg_isready), not just process liveness.
Set a start_period and enough retries for cold CI starts.
Check dependency logs first when the gate fails - the dependency is the real problem.