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.