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.

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

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

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

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

Verify the path and working directory in CI

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

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

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

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation