Docker Compose: dependency failed to start and the health check behind it
The container named in the error is the failing one. Inspect its health log, choose the right condition, and give slow databases a start period.

Introduction & Quick Summary
Symptom. docker compose up prints a wait, then an error, and the service you actually wanted to start has no logs at all:
Container demo-db-1 Started
Container demo-db-1 Waiting
Container demo-db-1 Error dependency db failed to start
dependency failed to start: container demo-db-1 is unhealthyThe application container was never created. docker compose logs app is empty, which sends people looking at the app's code, environment or Dockerfile for a problem that lives in the database container.
Cause. depends_on with the long syntax and condition: service_healthy makes Compose gate the dependent service on the dependency's health check. When the dependency reaches unhealthy, exits, or never defines a health check at all, Compose gives up and exits with dependency failed to start. The named container is the failing one; the service that was waiting is innocent.
Fix. Read the health log of the named container, then fix the check rather than the wait:
docker compose ps -a
docker inspect --format '{{json .State.Health}}' demo-db-1{"Status":"unhealthy","FailingStreak":2,"Log":[{"ExitCode":1,"Output":""}]}An empty Output with exit code 1 means the probe ran and failed. Exit code -1 with exec: "curl": executable file not found in $PATH means the probe never ran, because the image does not ship that binary. Those two cases have different fixes, and the health log is the only place that tells them apart.
Core Mechanics, Signatures & Reproducible Setup
Compose starts services in dependency order, but "order" only means "created after". Waiting for readiness is a separate opt-in through the long form of depends_on:
services:
db:
image: postgres:17
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres -d app"]
interval: 3s
timeout: 3s
retries: 10
start_period: 30s
app:
build: .
depends_on:
db:
condition: service_healthyThere are three conditions, and choosing the wrong one produces a timeout that looks like a health-check bug:
| Condition | Waits for | Fails the stack when |
|---|---|---|
service_started | the container to be created and started | almost never |
service_healthy | the health check to report healthy | the dependency turns unhealthy |
service_completed_successfully | a one-shot container to exit 0 | the container exits non-zero |
Reproduce the failure without touching a real database. The probe looks for a file that nothing creates:
services:
db:
image: alpine:3.21
command: ["sleep", "infinity"]
healthcheck:
test: ["CMD", "test", "-f", "/tmp/ready"]
interval: 2s
timeout: 2s
retries: 2
app:
image: alpine:3.21
command: ["echo", "app started"]
depends_on:
db:
condition: service_healthydocker compose up --abort-on-container-exit --exit-code-from app
# dependency failed to start: container ...-db-1 is unhealthy
docker inspect --format '{{json .State.Health}}' "$(docker compose ps -q db)"Change the dependency's command to sh -c 'touch /tmp/ready; sleep infinity' and the same file starts both services. That is the whole mechanism: the gate is working, and it is reporting a dependency that never became ready.
Key Comparison Table
| Symptom line | What it means | First command |
|---|---|---|
container X is unhealthy | probes ran and failed | docker inspect ... .State.Health |
container X is unhealthy with -1 exit | probe binary missing | check the image's tooling |
service "migrate" didn't complete successfully: exit 1 | one-shot job failed | docker compose logs migrate |
container X is unhealthy after a few seconds | retries too low for a cold start | raise start_period |
| stack hangs with no error | dependency has no health check | add one, or use service_started |
depends_on contains an invalid type | v2 file syntax at the top level | rename version: key, use compose.yaml |
| Service | Probe that works inside the image | Probe that fails |
|---|---|---|
postgres | pg_isready -U $POSTGRES_USER | curl localhost:5432 |
mysql | mysqladmin ping -h 127.0.0.1 | curl localhost:3306 |
redis | redis-cli ping | curl localhost:6379 |
nginx | wget -qO- localhost or nginx -t | curl in an image without it |
app with /healthz | wget -qO- http://localhost:3000/healthz | test -f /tmp/up |
Practical Edge Cases, Error Fixes & Deep Dive Code Examples
1. A dependency with no health check blocks forever
condition: service_healthy on a service that defines no healthcheck can never be satisfied. Depending on the Compose version this either hangs until the timeout or fails immediately:
# broken: service_healthy on a service with no healthcheck
depends_on:
cache:
condition: service_healthyEither add a check to the dependency or downgrade the condition honestly. service_started is not a readiness guarantee, so pair it with an application-level retry instead of pretending it is one.
2. start_period versus retries
start_period is a grace window in which failed probes do not count against retries. A database that initialises a data directory on first boot needs it; a database that restarts in two seconds does not. Confusing the two produces a stack that fails only on an empty volume:
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 2s
timeout: 2s
retries: 15
start_period: 60sMeasure the cold start once, then set start_period above it with margin. Raising interval instead slows every healthy start for no benefit.
3. One-shot migrations
A migration container is not "healthy"; it is "done". Using service_healthy on it is a category error, and using service_completed_successfully on a long-running service is the mirror mistake:
services:
migrate:
build: .
command: ["npm", "run", "db:migrate"]
depends_on:
db:
condition: service_healthy
api:
build: .
depends_on:
migrate:
condition: service_completed_successfully
db:
condition: service_healthyThe migration's own logs survive the failure, because the container is stopped and not removed: docker compose logs migrate still works after the run fails.
4. Restarting the dependency is not restarting the gate
depends_on is evaluated when the stack is created. Restarting a failed dependency with docker compose restart db does not re-run the gate for services that were never created. Bring the dependent service up explicitly:
docker compose up -d db
docker compose up -d app # now the gate is evaluated again
docker compose up --wait # or wait for everything healthy in one call--wait is the CI-friendly form: it returns non-zero if any service does not become healthy, which is more useful than parsing log text.
5. Compose v1 and v2 behave differently
The old docker-compose Python binary and the docker compose plugin both read depends_on, but only the plugin implements long-form conditions consistently, and only the plugin supports --wait. A version: "3.8" key at the top of a file written for v1 can also make the plugin ignore parts of the file:
docker compose version
docker-compose version 2>/dev/null || echo "v1 not compiled in"If the plugin prints a warning about the obsolete version key, delete the key. The schema is versioned by the CLI now.
6. Kubernetes is a different gate
This error is Compose-specific. In Kubernetes there is no depends_on; readiness probes gate traffic, init containers gate startup, and a pod waiting for a database simply crash-loops and backs off. Expecting the Compose behaviour from kubectl apply leads to pods that start before their dependency and log connection errors that nobody sequenced away.
Common Compilation/Runtime Mistakes & Version Gotchas
- Debugging the waiting service instead of the named one. The error names the failing container.
- Assuming the probe binary exists.
curlis absent from many slim images; use what the image ships. condition: service_healthywithout ahealthcheck. The condition can never be satisfied.- Using
service_healthyfor a migration job. The correct condition isservice_completed_successfully. - Raising
retriesbefore checkingstart_period. Cold starts need the grace window, not more failures. - Expecting
docker compose restartto re-run the gate. It does not. - Relying on
depends_onfor application-level readiness. A TCP-accepting database is not a migrated database; retry in the app too. - Keeping the obsolete
version:key. Newer Compose warns and may ignore parts of the file.
Keep the file valid with the docker-compose reference and the YAML validator; when a probe hits an HTTP endpoint, check the status code it returns with the HTTP status reference before deciding the service is unhealthy.
Reference: Compose depends_on and healthcheck in the services reference, and Control startup and shutdown order in Compose.
Official references
primary documentationThe Docker documentation that defines the behaviour this guide explains.
Try matching browser tools
All toolsSmall utilities that fit Docker work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Docker guides
All Docker guidesDocker: pull access denied, repository does not exist or may require login
The registry refused the pull for one of five reasons. Separate missing credentials from missing permission, wrong namespace and rate limits.
Docker Hub: toomanyrequests and the pull rate limit behind it
Shared CI addresses drain the anonymous quota. Log in, cache the bytes once, and stop pulling production images from Docker Hub.
Docker build: no space left on device while df shows free space
BuildKit cache lives outside docker system df. Measure it with buildx du, prune to a size budget and reorder the Dockerfile.
Docker: Cannot connect to the Docker daemon at unix:///var/run/docker.sock
An endpoint mismatch, a stopped daemon, or a missing socket mount. Resolve which of the three, then start, retarget, or mount.
More in Docker
All Docker guidesThe guides filed next to this one in Docker, in library order.