Docker Compose starts container B before container A is healthy
health status: startingShort answer
Compose does not wait for a container to be ready, only for it to be running. To make service B wait for A, give A a working healthcheck and put depends_on with condition: service_healthy on B. If A stays unhealthy, the healthcheck command itself is wrong, or its timing is too tight.
Fix it fast
1Find out which cause you have
See what Docker thinks of the dependency's health, and read the output of the last checks.
docker compose ps docker inspect --format '{{json .State.Health}}' $(docker compose ps -q db)2Match what you see, then jump to its fix
- 1
The app logs a connection error in the first seconds while the database container shows as runningdepends_on is written in short form, so Compose only waits for startFix - 2
State.Health shows failing checks with an exit code and output such as 'curl: not found' or 'connection refused'The healthcheck command fails inside the imageFix - 3
The dependency does become healthy later, but Compose already stopped with 'is unhealthy'The timing is too tight for a slow startFix
- 1
What does the error look like?
health status: startinghealth status: unhealthy
Cause 1 of 3
depends_on is written in short form, so Compose only waits for start
1Check
The short form (a list of service names) is the same as service_started. Compose by default does not wait for a container to be ready, only until it is running.
docker compose config | grep -A4 depends_on2Fix
Use the long form with condition: service_healthy, and give the dependency a healthcheck.
services:
web:
build: .
depends_on:
db:
condition: service_healthy
db:
image: postgres:18
healthcheck:
test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
interval: 10s
retries: 5
start_period: 30s
timeout: 10s3Verify
Bring the stack up and see web created only after db shows healthy.
docker compose up -d && docker compose psConfirmed by docs.docker.com
Cause 2 of 3
The healthcheck command fails inside the image
1Check
A healthcheck passes only when the command exits 0 (1 means unhealthy, 2 is reserved). The command runs inside the container, so a tool the image does not have, or a URL the app does not serve, keeps it unhealthy. Output of the check is kept in the health status.
docker inspect --format '{{range .State.Health.Log}}{{.ExitCode}} {{.Output}}{{end}}' $(docker compose ps -q db)2Fix
Use a command that exists in the image and tests the real thing (pg_isready for Postgres, a client ping for Redis, curl or wget only if installed). Use CMD-SHELL when you need shell variables.
healthcheck:
test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]3Verify
Run the same command by hand inside the container and check the exit code is 0.
docker compose exec db sh -c 'pg_isready -U $POSTGRES_USER -d $POSTGRES_DB; echo exit=$?'Confirmed by docs.docker.com
Cause 3 of 3
The timing is too tight for a slow start
1Check
A container turns unhealthy after retries (default 3) failed checks in a row. Failures inside start_period do not count, and the default start_period is 0s.
docker compose config | grep -B2 -A8 healthcheck2Fix
Give the container a start_period that covers a normal start, and raise retries or interval if checks are slow.
healthcheck:
test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
interval: 10s
timeout: 10s
retries: 5
start_period: 30s3Verify
Start from empty volumes once to see the slowest start pass.
docker compose down -v && docker compose up -d && docker compose psConfirmed by docs.docker.com
How do I stop it coming back?
- Add a healthcheck to every service another service depends on, and use service_healthy for it.
- Run the healthcheck command by hand in the container before trusting it.
- Still make the app retry its connection; a database can restart after startup.
- Use restart: true under depends_on when the app should restart after a Compose-managed dependency restart.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Servers
apk cannot find py-pip in an Alpine Docker image
py-pip (no such package):
On current Alpine releases there is no package called py-pip.
2 causes, each with a fixServers
ng serve runs in the container but localhost:4200 does not open
The browser cannot open localhost:4200 although ng serve is running in the container
ng serve listens on localhost by default, which inside a container is the container itself.
3 causes, each with a fixServers
Angular routes return 404 from nginx when you refresh or open a link
The home page loads, but refreshing /some/route shows an nginx 404
Angular routes like /users/42 are not files, so nginx looks for them on disk and returns 404.
3 causes, each with a fixServers
AH00558: Apache in Docker cannot reliably determine its fully qualified domain name
Set the 'ServerName' directive globally to suppress this message
AH00558 is a warning, not a crash.
2 causes, each with a fixServers
Apache in a Docker container logs AH01114 when it proxies to a backend
AH01114: HTTP: failed to make connection to backend: api
Apache's proxy worker could not open a connection to the address in ProxyPass.
5 causes, each with a fixServers
Apache logs SIGWINCH and exits on its own
the httpd container stops although nothing crashed
SIGWINCH is Apache's graceful-stop signal.
2 causes, each with a fix