Docker Compose "extends file not found" in CI

A service extends clause can pull configuration from another file via extends.file. That path is resolved relative to the compose file, so a wrong relative path, a file not checked out, or a base file outside the build context fails the parse.

What this error means

A docker compose command fails with cannot extend service "web": file ./base.yml not found or a similar missing-file error.

docker

service "web" cannot extend service "web" in ./common/base.yml: file ./common/base.yml not found

Common causes

A wrong relative path

The extends.file path is resolved relative to the compose file; an off-by-one directory makes it unresolvable.

The base file was not checked out

A shared base compose file living outside the repo (or excluded from the checkout) is missing in CI.

How to fix it

Fix the relative path to the base file

Point extends.file at the correct path relative to the compose file.

docker-compose.yml

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

Ensure the base file is present in CI

Check out or vendor the shared base file so the path exists at build time.

workflow

- uses: actions/checkout@v4
  with:
    submodules: true   # if base.yml lives in a submodule

How to prevent it

Keep extends.file paths relative to the compose file and inside the repo.
Vendor or submodule shared base files so they are always checked out.