docker compose says a service depends on an undefined service
service "app" depends on undefined service "db": invalid compose projectShort answer
Compose could not find the service named in depends_on in the model it loaded. Either the name does not match a service key, the target sits in a profile that is off, or it lives in a file you did not pass with -f. Run docker compose config to see what Compose actually loaded.
Fix it fast
1Find out which cause you have
Print the model Compose built from your files. If the target service is missing from the printed output, you have found the cause.
docker compose config --services2Match what you see, then jump to its fix
- 1
config --services lists a different name, such as database instead of dbThe depends_on name does not match a service keyFix - 2
The service exists in the file but is missing from config --servicesThe dependency sits in a profile that is not activeFix - 3
The database is in another file, or you ran -f with only one fileThe service is defined in a file that was not loadedFix
- 1
What does the error look like?
service "app" depends on undefined service "db": invalid compose projectdocker compose up fails before any container starts
Cause 1 of 3
The depends_on name does not match a service key
1Check
depends_on names services, and each name must be a key under services. It is not an image name or a container_name.
grep -n "depends_on" -A3 compose.yaml
docker compose config --services2Fix
Use the key under services exactly, and keep the indentation so db is a sibling of app.
services:
app:
build: .
depends_on:
- db
db:
image: postgres:173Verify
The model prints without the error.
docker compose config -q && echo okConfirmed by docs.docker.com
Cause 2 of 3
The dependency sits in a profile that is not active
1Check
A service with a profiles attribute starts only when its profile is on, and a dependency in another profile is not enabled for you.
grep -n "profiles" -B3 compose.yaml2Fix
Put the dependency in the same profile, remove its profile, or enable the profile for the run.
docker compose --profile debug up
# or
COMPOSE_PROFILES=debug docker compose up3Verify
The service appears in the list.
docker compose --profile debug config --servicesConfirmed by docs.docker.com
Cause 3 of 3
The service is defined in a file that was not loaded
1Check
Without -f, Compose reads compose.yaml and an optional compose.override.yaml. With -f, it merges only the files you list, in order.
docker compose -f compose.yaml config --services2Fix
Pass every file that defines services, base file first.
docker compose -f compose.yaml -f compose.db.yaml up3Verify
The merged model lists both services.
docker compose -f compose.yaml -f compose.db.yaml config --servicesConfirmed by docs.docker.com
How do I stop it coming back?
- Run docker compose config -q in CI so a broken reference fails before deploy.
- Keep core services such as the database without a profile, as Docker recommends for core application services.
- Pass the same -f list in every command and script, or set COMPOSE_FILE once.
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 says invalid compose project
docker compose up or config stops with a message that ends in invalid compose project
invalid compose project is a wrapper: the real reason is in the text before it.
2 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 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 fix