Docker "COPY failed: file not found in build context" in CI

By Daniel Zoghalchali·Latchkey

COPY can only see files inside the build context that .dockerignore has not excluded. A missing or ignored source path produces this exact error before the layer is built.

What this error means

A build fails on a COPY line with COPY failed: file not found in build context or excluded by .dockerignore: stat <path>: file does not exist.

docker

Step 5/12 : COPY dist/ /app/dist/
COPY failed: file not found in build context or excluded by .dockerignore: stat app/dist: file does not exist

Diagnose it: build context, cache, or platform?

A Dockerfile that builds locally and fails in CI usually differs in one of three ways: the build context contains different files, the layer cache is cold or poisoned, or the runner architecture does not match what the base image provides.

Terminal

# what is actually being sent as build context (dockerignore applies)
docker build --no-cache --progress=plain -t probe . 2>&1 | head -40

# what platform are you on, and what does the base image support?
docker version --format '{{.Server.Arch}}'
docker buildx imagetools inspect <base-image> | grep -i platform

# prove it is not a cache artefact
docker build --no-cache .

Common causes

Artifact not built before the COPY

A dist/ or build output directory does not exist yet because the build step that produces it runs outside the image or after it.

Path excluded by .dockerignore

A broad ignore pattern removed the directory from the context.

Wrong relative path

The COPY source is relative to the context root, but the file lives elsewhere.

How to fix it

Ensure the source exists in the context

Build or generate the artifact before docker build, or produce it in an earlier build stage.
Verify the path with ls before building.

Terminal

npm run build   # produces ./dist
docker build -t app .

Adjust .dockerignore

Remove or negate patterns that exclude files COPY needs.

.dockerignore

# .dockerignore
*
!dist/
!package.json

Keep the build context small and deterministic

A missing .dockerignore sends node_modules, .git, and build output to the daemon, which is slow and can change layer hashes between environments.
A COPY of a path that exists locally but is gitignored will fail in CI, because the runner only has what the checkout produced.
Multi-arch builds need buildx and QEMU set up explicitly; a plain docker build on an ARM runner silently produces an ARM image.

How to prevent it

Generate any copied artifacts before the build (or in a prior multi-stage stage), and keep .dockerignore tight but consistent with what the Dockerfile copies.

Frequently asked questions

What causes Docker "COPY failed: file not found in build context" in CI?

There are 3 common causes: artifact not built before the copy, path excluded by .dockerignore, and wrong relative path. A dist/ or build output directory does not exist yet because the build step that produces it runs outside the image or after it.

How do I fix Docker "COPY failed: file not found in build context" in CI?

There are 2 fixes depending on which cause you have: ensure the source exists in the context and adjust .dockerignore. Work through them in order, since the first is the most common.

What does Docker "COPY failed: file not found in build context" in CI actually mean?

A build fails on a COPY line with COPY failed: file not found in build context or excluded by .dockerignore: stat <path>: file does not exist.

How do I stop Docker "COPY failed: file not found in build context" in CI happening again?

Generate any copied artifacts before the build (or in a prior multi-stage stage), and keep .dockerignore tight but consistent with what the Dockerfile copies.