Docker Compose "extends file not found" in CI

By Kaveh Alemi·Latchkey

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.

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

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

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

Ensure the base file is present in CI

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

- 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.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation