COPY failed: file not found

"COPY failed: no such file or directory" has a non-obvious cause that traps experienced developers: the .dockerignore file silently excludes files before any COPY instruction executes. The build context (the directory sent to the Docker daemon) is filtered by .dockerignore first. If a pattern matches your source file, Docker's COPY cannot find it — not because the file does not exist, but because it was excluded from the build context. Common .dockerignore patterns that cause accidental exclusion: *.env excludes .env.production alongside .env.local; dist excludes the entire dist/ directory you intend to copy; broad **/*.test.js patterns can match test fixtures you need in the container. A second cause: the COPY source path is relative to the build context root, not to the current WORKDIR. COPY ./src . copies from {context}/src into the current WORKDIR, not from {WORKDIR}/src. In multi-stage builds, COPY --from=builder source paths are relative to the previous stage's WORKDIR, which is a different convention. Use docker build --progress=plain . to see the complete list of files sent to the build context. If your file is not listed, it was excluded by .dockerignore. Adding !path/to/needed-file negation rules to .dockerignore re-includes specific files excluded by broader patterns.