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

By Daniel Zoghalchali·Latchkey

A service waits on a dependency with condition: service_healthy, and the dependency never reported healthy. The healthcheck is failing or too slow, so compose aborts the dependent service.

What this error means

A docker compose up aborts with dependency failed to start: container <dep> is unhealthy. The dependent service never starts because its prerequisite did not go healthy.

dependency failed to start: container app-db-1 is unhealthy
Error response from daemon: container is unhealthy

Common causes

Healthcheck too strict or too fast

The interval/retries/start_period give a slow service (a database warming up) too little time to report healthy.

The dependency genuinely failed

Bad config, a crash, or a missing volume keeps the service from ever becoming healthy.

Wrong healthcheck command

The probe checks the wrong port, path, or tool that is absent in the image.

How to fix it

Give the dependency time and a correct probe

1. Add a start_period and reasonable retries so a slow-starting service can pass.
2. Ensure the healthcheck command actually tests readiness.

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

Debug the unhealthy container

1. Inspect the failing healthcheck output and the dependency logs.

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

How to prevent it

• Tune healthchecks with a start_period for slow services and verify the probe tests real readiness. If the dependency is slow only due to a transient resource blip, Latchkey managed runners auto-retry that transient failure rather than failing the whole job.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation