Docker Compose "container is unhealthy" (Healthcheck) in CI

A service Compose was waiting on never became healthy. dependency failed to start: container <name> is unhealthy means a depends_on: condition: service_healthy gate failed because the dependency's healthcheck did not pass within its retries.

What this error means

A docker compose up aborts with dependency failed to start: container app-db-1 is unhealthy. The dependent service never starts because the depended-on container's healthcheck kept failing.

docker

dependency failed to start: container app-db-1 is unhealthy
# api depends_on db with condition: service_healthy, and db's healthcheck never passed

Common causes

The healthcheck command never succeeds

A wrong probe (wrong port, missing tool, bad query) keeps returning non-zero, so the container stays unhealthy and the gate fails.

Start period / retries too short

A slow-starting service that needs longer than start_period x retries is marked unhealthy before it finishes booting.

The dependency actually failed to start

If the depended-on service crashes or misconfigures, its healthcheck legitimately never passes.

How to fix it

Write a correct healthcheck with adequate timing

Probe the real readiness endpoint and give it enough start period/retries.

docker-compose.yml

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

Diagnose why the dependency is unhealthy

Inspect the failing container's logs and health status.

Terminal

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

How to prevent it

Probe the actual readiness endpoint in healthchecks.
Set start_period/retries to cover real startup time.
Check dependency logs when a service_healthy gate fails.