Docker Compose "include" - Referenced File Not Found / Failed to Load in CI

The Compose include key pulls in other compose files. It fails when an included path does not exist, resolves relative to the wrong directory, or the Compose version is too old to understand include.

What this error means

A docker compose up/config fails loading an include with no such file or directory for the referenced compose file, or include is not supported. The main file is fine; the included one cannot be loaded.

docker compose output

error including compose file: stat ./services/db.yaml: no such file or directory
# top-level: include: [ ./services/db.yaml ]  resolved from the wrong directory

Common causes

The included path does not exist

A wrong or stale path under include points at a file that is not present (renamed, not committed, or excluded from checkout).

Relative path resolved from the wrong directory

Included paths resolve relative to the including file’s directory. Running from elsewhere, or a monorepo subpath mismatch, makes a correct-looking relative path resolve to nothing.

Compose too old for include

include is a newer Compose feature. An older plugin does not support the top-level key.

How to fix it

Point include at an existing path and confirm it is present

Use a path relative to the including file and verify it exists on the runner.

docker-compose.yml / Terminal

# compose.yaml
include:
  - ./services/db.yaml

# verify on the runner:
# ls -la services/db.yaml

Update Compose and validate the merge

Ensure a Compose version with include support and render the merged config.

Terminal

docker compose version
docker compose config   # shows the merged result or the include error

How to prevent it

Keep include paths relative to the including file and commit them.
Run docker compose config to validate the merged configuration.
Use a Compose version that supports include.