Docker build "failed to compute cache key: … not found": why COPY can't see your file

1. Know your build context

The last argument of docker build is the context — usually ., the current folder. Every source path in COPY and ADD is relative to the context, not to the Dockerfile and not to the folder you’re in:

docker build -t myapp .                              # context: current folder
docker build -t myapp -f docker/Dockerfile .         # Dockerfile in docker/, context still the root
docker build -t myapp docker/                        # context: docker/ — the rest of the project is invisible

The third line is the usual trap: with the Dockerfile in a subfolder, docker build docker/ sends only that subfolder, and COPY package.json ./ fails although package.json sits one folder up. Build from the project root with -f instead.

COPY ../shared /app/shared doesn’t work either: the context is a sandbox, and .. can’t leave it. BuildKit quietly treats the path as /shared inside the context and reports it as not found. Move the build context up a level (docker build -f app/Dockerfile . from the parent), or in Compose set context: .. and dockerfile: app/Dockerfile.

2. .dockerignore excludes it

The second most common cause, and the hardest to spot, because the file is in the folder. .dockerignore (in the root of the context) removes files from the context before it is sent:

node_modules
dist
*.lock
**/*.json

Here *.lock removes yarn.lock, and **/*.json removes every package.json and package-lock.json — and COPY package-lock.json ./ fails. Look for patterns that match the file in the error, including broad ones like *, **/*.json or a whole folder.

Two rules make .dockerignore different from .gitignore:

• Every pattern starts at the root of the context. node_modules excludes only ./node_modules; to exclude it in every folder, write **/node_modules.
• ! re-includes. An “ignore everything, then allow” file is fine, but every file the build needs must be allowed again:

*
!package.json
!package-lock.json
!src/

The .gitignore & .dockerignore Generator writes a .dockerignore that follows Docker’s rules — and it is checked with a real docker build for every stack.

3. Builds locally, fails in CI

If the build works on your machine and fails in GitHub Actions or GitLab CI, the CI checkout is different from your folder — it contains only what is in git:

git ls-files package-lock.json     # no output: the file isn't in the repository
git check-ignore -v package-lock.json

Typical cases:

• The lock file was never committed, or it’s in .gitignore. Commit package-lock.json (or poetry.lock, go.sum…): it makes builds repeatable anyway.
• The Dockerfile copies build output (COPY dist/ …) that you built locally with npm run build — and dist/ is (rightly) in .gitignore. Build it inside the image instead, in a build stage. That’s the multi-stage pattern the Dockerfile Generator writes, and the CI/CD Pipeline Generator writes a pipeline that builds it.
• Case. COPY Package.json ./ works on macOS and Windows, whose filesystems ignore case, and fails on the Linux CI runner.

4. The file comes from another stage

In a multi-stage build, COPY --from=build /app/dist ./dist reads from the build stage’s filesystem, not from the context. “not found” there means the previous stage didn’t produce that path:

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

Check where the build really writes: vite build writes to dist/, but Create React App writes to build/, Next.js to .next/, and tsc to whatever outDir says in tsconfig.json. To look inside a stage, build only that stage and open a shell in it:

docker build --target build -t myapp-build .
docker run --rm -it myapp-build sh -c "ls -la /app"

5. See exactly what’s in the context

When nothing above explains it, list what the builder actually receives. This throwaway Dockerfile copies the whole context into a tiny image and prints it:

docker build --no-cache --progress=plain -f - . <<'EOF'
FROM busybox
COPY . /ctx
RUN find /ctx -maxdepth 2 | sort
EOF

If the file isn’t in that list, it’s excluded (.dockerignore) or outside the context. The same output also shows things that shouldn’t be there — .git, node_modules, .env — which make the context slow to send and can leak into your image.