🚨 Docker Error Guide: 'depends_on undefined service' — Invalid Compose Project

Overview

Compose refuses to start your stack and rejects the whole project before any container is created:

service "web" depends on undefined service "databse": invalid compose project

This is a validation error, not a runtime failure. Compose builds a dependency graph from every depends_on entry and requires each referenced name to match an actual key under the top-level services: block. When a depends_on target does not exist — usually a typo or a service defined only in a file that was not loaded — Compose declares the project invalid and stops.

Symptoms

• docker compose up and docker compose config both fail immediately with invalid compose project.
• The named “undefined” service looks correct at a glance but differs by a typo, case, or hyphen/underscore.
• The stack works with one Compose file but fails when an override or a -f combination is used.
• The dependency exists in a different Compose file that is not being merged into the current invocation.
• No containers are created at all — the failure happens during project loading.

Common Root Causes

• Typo in the depends_on target. databse instead of database, or a mismatched case such as Redis vs redis.
• Service defined in an unloaded file. The dependency lives in docker-compose.override.yml or another -f file that the current command did not include.
• Renamed service, stale reference. A service key was renamed but a depends_on elsewhere still points at the old name.
• Wrong indentation. A service block is nested one level too deep, so Compose never registers it as a top-level service.
• Copy-paste across projects. A depends_on entry was pasted from another stack that had a queue or cache service this project does not define.

Diagnostic Workflow

Let Compose resolve and print the merged project. config fails with the same error but shows exactly which file combination it evaluated:

docker compose config
docker compose config --services

--services lists every service Compose actually recognizes; the depends_on target must appear in that list verbatim. If you use multiple files, reproduce the exact command that fails:

docker compose -f docker-compose.yml -f docker-compose.override.yml config --services

Inspect the offending definition. Here web references a name that does not match any key:

services:
  web:
    image: registry.example.com/myapp:1.4.2
    depends_on:
      - databse          # typo: no such service
  database:
    image: postgres:16

The corrected file makes the reference match the real key exactly:

services:
  web:
    image: registry.example.com/myapp:1.4.2
    depends_on:
      - database
  database:
    image: postgres:16

Then re-validate before starting anything:

docker compose config --services
docker compose up -d

Example Root Cause Analysis

A developer split a growing stack into docker-compose.yml (core services) and docker-compose.cache.yml (a redis service) so the cache could be toggled per environment. Locally they always ran docker compose -f docker-compose.yml -f docker-compose.cache.yml up, and it worked.

CI ran only docker compose up, which defaults to docker-compose.yml (plus an auto-loaded docker-compose.override.yml, if present). Because redis lived only in docker-compose.cache.yml, and CI never passed that -f, the web service’s depends_on: [redis] pointed at a service Compose could not see — producing service "web" depends on undefined service "redis": invalid compose project.

The fix was to make CI use the same file set: docker compose -f docker-compose.yml -f docker-compose.cache.yml up -d. Running docker compose config --services in CI confirmed redis was now present, and the project validated. The deeper lesson: a depends_on target is only defined relative to the specific set of files a given command loads.

Prevention Best Practices

• Always validate with docker compose config in CI before deploying; it catches undefined-service references without starting containers.
• Keep depends_on targets and service keys in sync when renaming services — search the whole file for the old name.
• Use the same -f file set everywhere (dev, CI, prod) so a service is never “defined” in one context and missing in another.
• Lint indentation. A misindented service block silently disappears from the top-level services: map; a YAML linter catches it. See the Dockerfile & Compose validator.
• Prefer explicit, lowercase, hyphen-free service names to reduce typo and case-mismatch surface area.

Quick Command Reference

# List every service Compose recognizes
docker compose config --services

# Reproduce the exact merged project a multi-file command sees
docker compose -f docker-compose.yml -f docker-compose.override.yml config

# Validate before starting
docker compose config && docker compose up -d

Conclusion

service depends on undefined service: invalid compose project means a depends_on entry names a service that is not in the merged project. Run docker compose config --services to see exactly which services Compose recognizes, then fix the typo, correct the indentation, or add the missing -f file so the dependency resolves. Validating in CI turns this from a deploy-time surprise into a fast, obvious failure you catch before it ships.