Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

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.

~5 min readDocker
#Docker#Docker Compose#Healthchecks#Troubleshooting
Three container blocks in a startup chain with the middle one red-lit and unhealthy behind a cyan gate

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:

code
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 unhealthy

The 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:

bash
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_healthy

There are three conditions, and choosing the wrong one produces a timeout that looks like a health-check bug:

ConditionWaits forFails the stack when
service_startedthe container to be created and startedalmost never
service_healthythe health check to report healthythe dependency turns unhealthy
service_completed_successfullya one-shot container to exit 0the 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_healthy
bash
docker 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 lineWhat it meansFirst command
container X is unhealthyprobes ran and faileddocker inspect ... .State.Health
container X is unhealthy with -1 exitprobe binary missingcheck the image's tooling
service "migrate" didn't complete successfully: exit 1one-shot job faileddocker compose logs migrate
container X is unhealthy after a few secondsretries too low for a cold startraise start_period
stack hangs with no errordependency has no health checkadd one, or use service_started
depends_on contains an invalid typev2 file syntax at the top levelrename version: key, use compose.yaml
ServiceProbe that works inside the imageProbe that fails
postgrespg_isready -U $POSTGRES_USERcurl localhost:5432
mysqlmysqladmin ping -h 127.0.0.1curl localhost:3306
redisredis-cli pingcurl localhost:6379
nginxwget -qO- localhost or nginx -tcurl in an image without it
app with /healthzwget -qO- http://localhost:3000/healthztest -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_healthy

Either 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: 60s

Measure 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_healthy

The 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:

bash
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:

bash
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. curl is absent from many slim images; use what the image ships.
  • condition: service_healthy without a healthcheck. The condition can never be satisfied.
  • Using service_healthy for a migration job. The correct condition is service_completed_successfully.
  • Raising retries before checking start_period. Cold starts need the grace window, not more failures.
  • Expecting docker compose restart to re-run the gate. It does not.
  • Relying on depends_on for 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 documentation

The Docker documentation that defines the behaviour this guide explains.

Try matching browser tools

All tools

Small utilities that fit Docker work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Docker guides

More in Docker

All Docker guides

The guides filed next to this one in Docker, in library order.