Docker Compose rejects depends_on with a condition and says it should be an array
depends_on contains an invalid type, it should be an arrayShort answer
The short depends_on form is a list of service names and cannot hold a condition. Conditions need the long form, a map with the service name as the key. Also check you run Compose v2 (docker compose), because the old docker-compose v1 tool is unmaintained and may reject files that v2 accepts.
Fix it fast
1Find out which cause you have
Print which Compose binary and version runs your file, and let it validate the file. The error message gives the service and key.
docker compose version docker compose config2Match what you see, then jump to its fix
What does the error look like?
depends_on contains an invalid type, it should be an arrayCompose will not start the project after condition: service_healthy was added to depends_on
Cause 1 of 2
condition written under the short list syntax
1Check
In the short syntax, depends_on lists service names only and means the same as service_started. Compose creates dependencies first but does not wait for them to be healthy.
grep -n -A6 "depends_on" compose.yaml2Fix
Switch to the long syntax: each dependency becomes a key with its own condition. service_healthy needs a healthcheck on that dependency.
services:
web:
build: .
depends_on:
db:
condition: service_healthy
db:
image: postgres:18
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 5s
timeout: 5s
retries: 103Verify
Compose accepts the file and prints it merged.
docker compose configConfirmed by docs.docker.com
Cause 2 of 2
The file is run by docker-compose v1, not Compose v2
1Check
docker-compose is Compose v1, written in Python; docker compose is Compose v2, built into the Docker CLI. Docker's migration page says v1 is no longer maintained and users should move to v2.
docker-compose --version
docker compose version2Fix
Install the Docker Compose plugin and run docker compose instead of docker-compose, with the same file.
docker compose up -d3Verify
The same file now starts, and the condition is respected.
docker compose psConfirmed by docs.docker.com
How do I stop it coming back?
- Write depends_on in the long syntax whenever a service needs a condition, a restart or required setting.
- Remove the old top-level version line; Compose treats it as obsolete and only warns about it.
- Run docker compose config in CI so a bad file fails before deploy.
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
Docker Compose starts container B before container A is healthy
health status: unhealthy
Compose does not wait for a container to be ready, only for it to be running.
3 causes, each with a fixServers
Compose refuses the version line in docker-compose.yml
You might be seeing this error because you're using the wrong Compose file version.
This error comes from the old Python docker-compose v1 tool.
3 causes, each with a fixServers
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 fix