Docker Compose: 'service "web" depends on undefined service "db": invalid compose project'

service "web" depends on undefined service "db": invalid compose project — a depends_on entry names a service that Compose cannot find among the project's active services. Make the name under depends_on match a key under services: exactly, or, if that service has profiles:, enable the profile.

Compose v5.6.1 printed this same line for a misspelt name, for a name that only matches a container_name, and for a service that exists but sits in a profile that is not enabled. docker compose config --services lists the services Compose actually sees, which settles it in one command.

The error

PS> docker compose up -d
service "web" depends on undefined service "db": invalid compose project

The file behind it, where the database service is called database:

name: fix7-dep

services:
  web:
    image: alpine:latest
    command: ["sleep", "300"]
    depends_on:
      - db

  database:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: example-only

Why it happens

Before it creates anything, Compose builds the project: it reads the file, keeps the services whose profiles are active, and then checks every reference between them. A depends_on entry is a service name, the key under services:. Here the key is database and the dependency says db, so the check fails and nothing is created; docker compose config fails with the same line. Adding container_name: db to the database service did not help in the test, because a container name is not a service name.

The second cause is less obvious. When db was defined correctly but carried profiles: ["data"], a plain docker compose up -d left it out of the project, and web pointed at a service that, for that run, did not exist. The message was word for word the same. An indentation slip, with db: pushed to the left margin, gives a different and earlier error: validating ...\compose.yaml: additional properties 'db' not allowed.

The fix

Rename the key so the two sides match, then check what Compose sees before starting:

  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: example-only

PS> docker compose config --services
db
web
PS> docker compose up -d
 Container fix7-dep-db-1 Started
 Container fix7-dep-web-1 Started

Changing the depends_on entry to database instead passed the same check in the test; only the match matters. The up output is trimmed to its last two lines. For the profile case, keep the file and enable the profile, on the command line or with the COMPOSE_PROFILES environment variable, which listed both services in the test as well:

PS> docker compose --profile data config --services
db
web
PS> docker compose --profile data up -d
 Container fix7-dep-db-1 Started
 Container fix7-dep-web-1 Started

Until the profile is on, Compose refuses the whole project, not just web: neither container was created in the failed run.

How it was reproduced

Docker Desktop 4.96.3 with engine 29.9.2 and Docker Compose v5.6.1, run from Windows PowerShell 5.1, with the cached alpine:latest and postgres:16 images. Four small files, one per case (wrong key, container_name, profile, indentation), and the corrected one. The project name fix7-dep and the password example-only are the test's own; the long scratch path in the indentation error is shortened, nothing else in it changed.

Frequently asked

What does 'depends on undefined service' mean in Docker Compose?

A depends_on entry names a service that is not among the active services of the project. Usually the key under services is spelt differently; it also happens when the service belongs to a profile that is not enabled.

Does depends_on use the container name or the service name?

The service name, the key under services. In the test, giving the database service container_name: db did not satisfy depends_on: db; Compose still reported an undefined service.

Why does Compose say undefined service when the service is in the file?

Check its profiles. A service with profiles joins the project only when one of them is enabled with --profile or the COMPOSE_PROFILES variable; until then depends_on cannot see it.

More decoded errors in the Fixes category. A full Compose file for an app and its database, with depends_on and a health check, is in Compose: the app and its database from one file.