Docker Compose "service failed to build" - Diagnose Compose Build Errors

By Kaveh Alemi·Latchkey

Compose delegates building to the same engine as docker build, so a compose build failure is really a Dockerfile or context problem reported through compose.

What this error means

docker compose build or docker compose up --build stops on one service with a build error. The underlying cause is identical to a plain docker build failure for that service.

[+] Building 2.1s (6/9)
 => ERROR [api builder 4/6] COPY requirements.txt .
failed to solve: failed to compute cache key: "/requirements.txt": not found

Common causes

Wrong build context or Dockerfile path

The build.context and build.dockerfile in your compose file determine which files are visible. A mismatched context is the most common cause of "not found" during compose build.

A dependency service is not built/ready

Services that depend on a base image built by another service can fail if build order or depends_on is wrong.

How to fix it

Verify context and Dockerfile

Make the build context explicit and confirm the paths your Dockerfile copies actually exist relative to that context.

services:
  api:
    build:
      context: ./api
      dockerfile: Dockerfile
    # COPY paths in ./api/Dockerfile are relative to ./api

Build with full logs

docker compose build --progress=plain --no-cache api

How to prevent it

• Keep each service’s build context minimal and explicit.
• Use .dockerignore per context.
• Pin image versions used across services so cached layers are reused.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation