Docker Compose "extends" Errors - Circular Reference / File Not Found in CI

Compose extends lets one service inherit another’s config. It fails when services extend each other in a loop, point at a service that does not exist, or reference an extends file that is not found.

What this error means

A docker compose config/up fails during config resolution with circular reference, Cannot extend service "<x>" which does not exist, or an extends-file not-found error. The services never start because the config cannot be assembled.

docker compose output

service "api" can not be used, circular reference:
api -> base -> api
# or:
Cannot extend service "bace" in docker-compose.base.yml: service does not exist

Common causes

Two services extend each other

A loop (api extends base, base extends api) cannot be resolved into a single config, so Compose reports a circular reference.

Extending a service that does not exist

A typo in the service: name under extends, or a service removed from the base file, leaves nothing to inherit from.

The extends file path is wrong

An extends: { file: ... } pointing at a missing or mis-pathed file (relative to the current compose file) cannot be loaded.

How to fix it

Break the cycle and reference real services

Make extension one-directional and point at a service that exists in the named file.

docker-compose.yml

# docker-compose.yml
services:
  api:
    extends:
      file: docker-compose.base.yml
      service: base   # 'base' must exist and must NOT extend 'api'

Validate the merged config

Render the resolved config to surface the extends chain and any bad reference.

Terminal

docker compose -f docker-compose.yml config

How to prevent it

Make extends one-directional from concrete services to base services.
Reference exact service names and correct file paths in extends.
Run docker compose config in CI to validate the merge before up.