Docker Compose "depends on undefined service" in CI

A depends_on referenced a service that does not exist. service "<a>" depends on undefined service "<b>" means the dependency name is wrong - a typo, a service that was removed, or one expected from an include/override that is not present.

What this error means

A docker compose up/config fails with service "api" depends on undefined service "databse": invalid compose project (or similar). The dependency target is not among the defined services.

docker

service "api" depends on undefined service "databse": invalid compose project
# depends_on: [databse]  - typo of "database"

Common causes

A typo in the dependency name

A misspelled service in depends_on does not match any defined service, so Compose flags it as undefined.

The depended-on service was removed or renamed

Deleting/renaming a service without updating the depends_on that references it leaves a dangling dependency.

The service lives in an include/override not loaded

A dependency defined in a file that is not part of this Compose invocation appears undefined.

How to fix it

Match depends_on to a defined service

Fix the name so it matches an actual service key.

docker-compose.yml

services:
  database:
    image: postgres:16
  api:
    image: myorg/api:1.4.2
    depends_on:
      - database

Include the file that defines the dependency

Load every file that defines the referenced services in the same command.

Terminal

docker compose -f docker-compose.yml -f docker-compose.db.yml config

How to prevent it

Keep depends_on names in sync when renaming/removing services.
Load all compose files that define referenced services together.
Validate with docker compose config before deploying.