Fix docker compose error: Service depends on undefined service

What this error means

Docker Compose raises this when a service lists depends_on entries that do not correspond to any defined (and active) service in the current Compose project. Typical causes include typos, YAML indentation issues, missing files in a multi-file setup, inactive profiles, or confusing container names with service names.

Minimal working example (MWE)

This compose file is valid and will not trigger the error because every depends_on target is defined under services.

data:
  # Named volume for persistence (optional)
  name: demo_data

services:
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: example
    volumes:
      - data:/var/lib/postgresql/data

  api:
    image: alpine:3.19
    depends_on:
      - db
    command: ["sh", "-c", "echo API started; sleep 60"]

Run it:

docker compose up -d

If you change depends_on to reference database instead of db, Compose will error: Service 'api' depends on service 'database' which is undefined.

Quickstart: immediate fix checklist

• Verify service keys under services exactly match depends_on values.
• Check YAML indentation: all services must be direct children of services:.
• If using profiles, activate the profile that defines the dependency with --profile or COMPOSE_PROFILES.
• If using multiple files, include the file that defines the dependency with -f flags, in the right order.
• Do not use container_name or network aliases in depends_on. Only service keys are valid.
• Use docker compose config to render the merged, interpolated configuration and confirm the service exists.

Common causes and how to fix them

Step-by-step diagnosis and fixes

1. Render the effective configuration

• Command:

docker compose config

• Look for the services section. If the dependency name isn’t listed, Compose can’t find it.

1. Check spelling and case

• Service keys are identifiers under services:. depends_on must match them character-for-character.
• Example (broken):

services:
  db:
    image: postgres:16
  api:
    image: alpine:3.19
    depends_on:
      - database  # wrong

• Fix:

services:
  db:
    image: postgres:16
  api:
    image: alpine:3.19
    depends_on:
      - db  # correct

1. Verify YAML structure

• All services must be direct children of services:.
• Example (broken):

services:
  group:
    db:  # wrong nesting; db is NOT a service here
      image: postgres:16

• Fix:

services:
  db:
    image: postgres:16

1. Confirm multi-file composition

• If the dependency is defined in another file, include it.

docker compose -f compose.yml -f compose.dev.yml config

• The order matters: later files override earlier ones. Ensure the file that defines the service is included.

1. Activate required profiles

• If a service has profiles:

services:
  db:
    image: postgres:16
    profiles: ["db"]
  api:
    image: alpine:3.19
    depends_on:
      - db

• Start with the profile enabled:

docker compose --profile db up -d api
# or
COMPOSE_PROFILES=db docker compose up -d api

1. Avoid confusing names

• Use service keys (db), not container_name values or network aliases.
• Network aliases are for DNS inside the network, not for depends_on.

1. Check environment interpolation

• If using environment variables in depends_on:

services:
  db:
    image: postgres:16
  api:
    image: alpine:3.19
    depends_on:
      - ${DB_SERVICE:-db}

• Ensure DB_SERVICE expands to db. Verify with:

DB_SERVICE=db docker compose config | grep -A3 api:

1. Validate extends usage

• When using extends, confirm the referenced file and service exist.

services:
  web:
    extends:
      file: base.yml
      service: web-base

• Run docker compose -f base.yml -f compose.yml config to ensure resolution.

Pitfalls

• Mixing docker-compose (v1) and docker compose (v2) behavior; prefer the modern docker compose plugin.
• Relying on container_name in depends_on; always use service keys.
• Assuming depends_on makes services “ready.” It only orders startup. Add healthchecks if you need readiness gating.
• Inactive profiles silently removing services you thought were present.
• Typos masked by YAML anchors/aliases; always confirm with docker compose config.

Performance notes

• Keep compose files minimal for the task; unused services slow down planning and can complicate dependency graphs.
• Use profiles to limit what starts for a workflow (e.g., only api and db), which reduces startup time and resource usage.
• depends_on orders starts but does not block on readiness. Add healthchecks and, if needed, conditions to avoid crash loops and wasted retries.
• docker compose config is fast and helps catch errors before pulling images or starting containers.

Tiny FAQ

• Q: Can I depend on a container from another Compose project? A: No. depends_on works only within the same Compose project (the current files and active profiles).

• Q: Can I use container_name in depends_on? A: No. Use the service key under services:, not the container’s runtime name.

• Q: How do I verify which services are active with profiles? A: Render the config with docker compose --profile <name> config and inspect the services list.

• Q: Does depends_on wait for the database to be ready? A: No. Add a healthcheck to the database and implement readiness logic in your app, or use conditions if supported.