Docker Compose "build context path does not exist" in CI

By Daniel Zoghalchali·Latchkey

A service build: context is resolved relative to the compose file's directory. When that path does not exist - a wrong relative path, a checkout that did not include the directory, or running compose from the wrong place - Compose cannot prepare the context and the build fails.

What this error means

A docker compose build/up fails with unable to prepare context: path "<dir>" not found. The build context directory is missing relative to the compose file.

docker

unable to prepare context: path "/workspace/services/api" not found

Diagnose it: read the resolved config, not the file you wrote

Compose merges override files, interpolates variables, and applies defaults before it does anything. Most Compose failures in CI are visible in the resolved configuration and invisible in the source file, because the value you are debugging came from an unset variable that quietly became an empty string.

Terminal

# the fully merged, interpolated configuration Compose will actually run
docker compose config

# fail loudly on unset variables instead of silently interpolating empty
docker compose --env-file .env config --quiet || echo "invalid"

# which override files were picked up
docker compose config --services

Common causes

A wrong relative build context

The context: path does not resolve to an existing directory relative to the compose file.

The directory is absent in the checkout

A sparse or partial checkout may not include the service's build directory.

How to fix it

Point the context at the real directory

Set context to the correct path relative to the compose file.
Confirm it exists before building.

docker-compose.yml

services:
  api:
    build:
      context: ./services/api
      dockerfile: Dockerfile

Verify the path and working directory in CI

List the context directory and run compose from the compose file's location.

Terminal

ls -la services/api
docker compose -f docker-compose.yml build api

Bind mounts behave differently on a runner

A relative bind source is resolved against the compose file location, not the working directory of the shell that invoked it.
The host path must exist before up. Compose creates missing directories for named volumes but not for bind mounts, and the failure surfaces as a mount error rather than a missing-path error.
On a CI runner the workspace path differs from your machine, so any absolute host path in a compose file is a portability bug waiting for its first CI run.
Prefer named volumes for anything that does not genuinely need to be read from the host. They remove the whole class of problem.

How to prevent it

Use correct context paths relative to the compose file.
Ensure the checkout includes all build directories.
Run compose from the directory holding the compose file.

Frequently asked questions

What causes Docker Compose "build context path does not exist" in CI?

There are 2 common causes: a wrong relative build context and the directory is absent in the checkout. The context: path does not resolve to an existing directory relative to the compose file.

How do I fix Docker Compose "build context path does not exist" in CI?

There are 2 fixes depending on which cause you have: point the context at the real directory and verify the path and working directory in ci. Work through them in order, since the first is the most common.

What does Docker Compose "build context path does not exist" in CI actually mean?

A docker compose build/up fails with unable to prepare context: path "<dir>" not found.

How do I stop Docker Compose "build context path does not exist" in CI happening again?

Use correct context paths relative to the compose file. The prevention section lists 3 changes that keep it from recurring.