Compose "container for service ... is unhealthy" with depends_on in CI

By Kaveh Alemi·Latchkey

With depends_on: condition: service_healthy, Compose waits for the dependency's healthcheck to report healthy before starting the dependent service. If the healthcheck never passes within its retries, Compose aborts with the dependency marked unhealthy.

What this error means

A docker compose up fails with "dependency failed to start: container <name> is unhealthy" or "service \"app\" didn't complete successfully: container for service \"db\" is unhealthy".

dependency failed to start: container app_db_1 is unhealthy

Common causes

The dependency never becomes healthy

The service starts slowly or crashes, so its healthcheck keeps failing until retries are exhausted.

A wrong or too-strict healthcheck

The healthcheck command, interval, or timeout does not match how the service actually reports readiness, so it fails even when the service works.

How to fix it

Make the healthcheck match readiness

1. Run the healthcheck command manually inside the container to confirm it passes.
2. Tune interval, timeout, retries, and add start_period for slow boots.
3. Re-run so the dependency reports healthy in time.

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

Inspect the dependency logs when it stays unhealthy

Read the dependency logs to see why it never becomes ready, then fix the service or its config.

docker compose logs db

How to prevent it

• Write healthchecks that match the service's real readiness.
• Set a generous start_period for services that boot slowly.
• Check dependency logs when a healthcheck never passes.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation