Tutorial cover

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

The error means the healthcheck of a service that another service waits for (depends_on with condition: service_healthy) keeps failing. Docker Compose gives up and does not start the dependent service. The usual cause is that the healthcheck command does not exist in the image: curl is missing from most -alpine images.

The error

A database with a healthcheck and an app that waits for it:

services:
  db:
    image: postgres:17-alpine
    environment:
      POSTGRES_PASSWORD: example
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:5432"]
      interval: 5s
      timeout: 3s
      retries: 3
  app:
    image: nginx:1.27-alpine
    depends_on:
      db:
        condition: service_healthy

docker compose up -d waits about 15 seconds and stops:

 Container broken-db-1 Started
 Container broken-db-1 Waiting
 Container broken-db-1 Error dependency db failed to start
dependency failed to start: container broken-db-1 is unhealthy

app stays in Created, the database is running but marked unhealthy:

$ docker compose ps -a
SERVICE   STATUS
app       Created
db        Up 15 seconds (unhealthy)

Find the reason

Docker keeps the output of the last healthcheck runs:

docker inspect broken-db-1 --format '{{json .State.Health.Log}}'

The last entry shows the real problem:

OCI runtime exec failed: exec failed: unable to start container process:
exec: "curl": executable file not found in $PATH

The healthcheck runs inside the container, so the command must exist in that image. Check before you write it:

docker run --rm postgres:17-alpine sh -c 'which curl wget pg_isready'

postgres:17-alpine has wget and pg_isready, but no curl. nginx:1.27-alpine has both curl and wget. Images built FROM scratch or distroless have no shell at all, so CMD-SHELL does not work there.

Fix

Use the tool made for the service. For PostgreSQL it is pg_isready:

services:
  db:
    image: postgres:17-alpine
    environment:
      POSTGRES_PASSWORD: example
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 3s
      retries: 5
      start_period: 10s
  app:
    image: nginx:1.27-alpine
    depends_on:
      db:
        condition: service_healthy
 Container unhealthy-db-1 Healthy
 Container unhealthy-app-1 Starting
 Container unhealthy-app-1 Started

$ docker compose ps
SERVICE   STATUS
app       Up Less than a second
db        Up 6 seconds (healthy)

start_period gives a slow service time to start: failures during that period do not count towards retries.

Other causes

If the command exists, but the service is still unhealthy:

Cause What you see in .State.Health.Log Fix
The service starts longer than interval × retries connection refused in the first runs, then nothing Add start_period, raise retries
Wrong port or path in the check connection refused, 404 Check the port inside the container, not the published one
The service listens only on another address connection refused on localhost Check against the address the service listens on
Wrong user or database in pg_isready / mysqladmin ping no response, Access denied Use the same user as in the service environment
The service itself crashes the container restarts, docker compose logs <service> shows the error Fix the service; the healthcheck only reports it

Ready-made checks for popular images:

# PostgreSQL
test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
# MySQL / MariaDB
test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
# Redis
test: ["CMD", "redis-cli", "ping"]
# HTTP service in an Alpine image (wget is in BusyBox)
test: ["CMD", "wget", "-q", "--spider", "http://localhost:8080/health"]

$$ keeps the variable for the container: Compose would otherwise substitute it from your .env when it reads the file.

The same in one click

Jambotron runs your docker-compose.yml as it is: depends_on with service_healthy works, and if a service stays unhealthy, the deployment log shows which service and why. Upload a ZIP with the compose file or connect a Git repository, press Deploy, then open the app on a domain with HTTPS.

See also

Back to list