🚨 Docker Error Guide: 'COPY failed: file not found in build context' Build Context Errors

Exact Error Message

A COPY (or ADD) instruction fails when its source path cannot be found in the build context. BuildKit reports it like this:

 > [stage-0 3/5] COPY ./config/app.yaml /etc/app/app.yaml:
------
COPY failed: file not found in build context or excluded by .dockerignore: stat config/app.yaml: file does not exist

ADD produces the parallel message, and a multi-stage COPY --from surfaces a cache-key variant:

ADD failed: file not found in build context or excluded by .dockerignore: stat dist/release.tar.gz: file does not exist

failed to solve: failed to compute cache key: failed to calculate checksum of ref ...: "/app/dist": not found

What It Means

When you run docker build, Docker first sends a build context — the directory you pass as the final argument (usually .) — to the builder, minus anything matched by .dockerignore. Every COPY <src> <dst> and ADD <src> <dst> resolves <src> relative to the root of that context, not relative to the Dockerfile’s directory. If the file is not inside the transmitted context (because of the path, the context root, or a .dockerignore rule), Docker cannot stat it and the step fails. The or excluded by .dockerignore clause is a hint that the file may physically exist but was filtered out before the builder ever saw it.

Common Causes

• Path relative to the Dockerfile, not the context — COPY ../shared/lib . fails because .. escapes the context root; sources must live under the context.
• File excluded by .dockerignore — a broad pattern like * , config, or dist silently strips the file from the context.
• Wrong build context — running docker build -f sub/Dockerfile . when the file is under sub/ (so the context should be sub/), or vice versa.
• Case sensitivity — COPY Config/app.yaml when the directory is config/; the Linux builder is case-sensitive even if your host filesystem is not.
• File generated outside the context — an artifact built by CI into a directory that is not part of the context sent to Docker.
• Multi-stage COPY --from artifact missing — the earlier stage never produced the path being copied, yielding failed to compute cache key: ... not found.
• Trailing-slash semantics — COPY src dst where dst lacks a trailing slash and src is multiple files, or a directory-vs-file mismatch.

How to Reproduce the Error

Reference a file that the .dockerignore excludes:

# Dockerfile
FROM alpine:3.20
COPY config/app.yaml /etc/app/app.yaml

# .dockerignore
config

docker build -t copy-demo .

COPY failed: file not found in build context or excluded by .dockerignore: stat config/app.yaml: file does not exist

The file exists on disk, but .dockerignore removed config from the context, so the builder cannot see it.

Diagnostic Commands

Re-run with plain progress to see exactly which path the builder tried to stat:

docker build --progress=plain --no-cache -t copy-demo . 2>&1 | grep -A3 'COPY\|ADD failed'

Inspect the .dockerignore rules that shape the context:

cat .dockerignore

List the actual contents of the context directory and the exact case of the target path:

ls -la ./config/
find . -iname 'app.yaml' -not -path './.git/*'

For a multi-stage copy, confirm the earlier stage produced the artifact by building just that target:

docker build --target build -t copy-demo:stage . && \
  docker run --rm copy-demo:stage ls -la /app/dist

Check what the context actually transmits (size hints at over-broad inclusion):

du -sh . ; docker system df

Step-by-Step Resolution

1. Make the source path context-relative. The source must live under the context root. If you need files from a parent directory, move the build context up and point -f at the Dockerfile:

# Dockerfile in app/, but it needs ../shared
docker build -f app/Dockerfile -t app .

COPY shared/lib /opt/lib
COPY app/ /srv/app

2. Adjust .dockerignore. Stop excluding files you need to copy. Prefer narrow patterns and re-include with !:

**/node_modules
dist/tmp
!dist/release.tar.gz

3. Use the right build context. The final argument to docker build defines the context root. If the file is under sub/, either build with context sub/ or reference sub/file from a parent context:

docker build -f sub/Dockerfile -t app sub/

4. Fix case mismatches. Match the on-disk case exactly. COPY config/app.yaml (lowercase) if the directory is config, not Config.

5. Ensure generated artifacts are inside the context. Have CI write build outputs into the context directory before docker build, or copy them in. A file produced into /tmp outside the context will never be visible.

6. Fix multi-stage COPY --from. Confirm the source stage actually creates the path, and reference the stage by its AS name:

FROM node:20 AS build
WORKDIR /app
RUN npm run build           # produces /app/dist

FROM nginx:1.27
COPY --from=build /app/dist /usr/share/nginx/html

7. Mind trailing-slash semantics. When copying a directory or multiple files, give the destination a trailing slash so Docker treats it as a directory: COPY src/ /app/src/.

How to Prevent the Issue

• Keep a tight, reviewed .dockerignore and add a comment next to any rule that could hide files a COPY needs.
• Standardise the build context — always build from the repo root with -f path/to/Dockerfile so paths are predictable.
• Reference paths in lowercase and avoid relying on host case-insensitivity that the Linux builder does not share.
• In multi-stage builds, name every stage with AS and copy by name, never by stage index.
• Add a CI smoke build (docker build --target build) that fails early if an expected artifact path is missing.

Related Docker Errors

• failed to solve with frontend dockerfile.v0 — the broader BuildKit solve error this often appears under; see the failed to solve guide.
• failed to compute cache key: ... not found — the multi-stage form of this same problem, covered above and in the failed-to-solve guide.
• no space left on device while sending a large context — see the no space left on device guide.
• More build fixes in the Docker guides.