Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

docker compose says a service depends on an undefined service

Errorservice "app" depends on undefined service "db": invalid compose project

Short 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.

  • Applies to Docker Compose 2.40, Docker Engine 28
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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 --services
  2. 2Match what you see, then jump to its fix

    1. 1config --services lists a different name, such as database instead of dbThe depends_on name does not match a service keyFix
    2. 2The service exists in the file but is missing from config --servicesThe dependency sits in a profile that is not activeFix
    3. 3The database is in another file, or you ran -f with only one fileThe service is defined in a file that was not loadedFix

What does the error look like?

  • service "app" depends on undefined service "db": invalid compose project
  • docker 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 --services

2Fix

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

3Verify

The model prints without the error.

docker compose config -q && echo ok

Confirmed by docs.docker.com

Did this fix it?

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.yaml

2Fix

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 up

3Verify

The service appears in the list.

docker compose --profile debug config --services

Confirmed by docs.docker.com

Did this fix it?

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 --services

2Fix

Pass every file that defines services, base file first.

docker compose -f compose.yaml -f compose.db.yaml up

3Verify

The merged model lists both services.

docker compose -f compose.yaml -f compose.db.yaml config --services

Confirmed by docs.docker.com

Did this fix it?

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 fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.