Docker Failed to Compute Cache Key: Fix “Not Found” in COPY

Docker · BuildKit · buildxCOPY · build contextLast reviewed Oct 17, 2026

Difficulty: Easy–ModerateRisk: Low for inspection; medium for configuration changes

Quick answer: When BuildKit reports failed to compute cache key: failed to calculate checksum ... "/path": not found during COPY, the source is unavailable to that build stage. Check the positional build context, ignore files, exact path/capitalization and COPY --from output. Deleting build cache will not restore a missing source.

🎯 This guide matches when:

The failing instruction usually contains COPY or ADD, followed by failed to compute cache key, failed to calculate checksum, and a missing quoted path. Record the exact path. If your error is failed to read dockerfile, this guide is not the correct branch.

🔎 Quick Check — identify the build context

In docker build -f docker/Dockerfile ., the trailing . is the build context. -f selects the Dockerfile, not the context. A build that reads only a Dockerfile from standard input supplies no local filesystem context for host-file COPY instructions. Pass a context explicitly with the Dockerfile-from-stdin option and a trailing context directory. Compare each failing source with the selected context root.

pwd
ls -la
ls -la path/to/source
docker build --progress=plain -f docker/Dockerfile -t myapp:diagnostic .

Verify: the same COPY instruction now completes. If not, inspect ignore rules before changing the Dockerfile.

Choose the missing-source branch

Source missing from build contextCorrect the trailing positional build context argument.

File exists but BuildKit cannot see itInspect .dockerignore and Dockerfile-specific ignore rules.

Only Linux CI failsCompare filename case, checkout, generated files and CI working directory.

COPY --from=builder failsInspect the producing stage output rather than the host filesystem.

Remote Git context failsVerify selected branch, subdirectory and remote checkout contents.

Fix #1 — correct the build context

Suppose package.json lives at the repository root and Dockerfile lives in docker/. If your Dockerfile says COPY package.json ./, run from the repository root:

docker build --progress=plain -f docker/Dockerfile -t myapp:diagnostic .

Using docker/ as the trailing argument would omit root-level package.json. A COPY source that uses ../ cannot escape the context to reach a parent directory; Docker resolves sources from the context root and removes parent-directory navigation. Select a safe context that contains the needed file instead of expanding it blindly to include credentials or private files.

Verify: the highlighted COPY package.json step succeeds.

Fix #2 — check .dockerignore exclusions

Review .dockerignore at the context root. For a nondefault Dockerfile, also inspect a sibling file such as docker/build.Dockerfile.dockerignore, which takes precedence. Docker ignore exceptions use !; when multiple patterns match, the last matching rule determines inclusion.

Change only the necessary rule; do not remove all exclusions or expose .env, private keys or tokens.

Verify: rebuild with the original command and confirm the missing source is now present.

Fix #3 — inspect filename case and CI inputs

Linux builders distinguish Config.json from config.json. Check the exact tracked path with git ls-files. Compare the CI working directory, checkout depth/submodules, generated artifacts and build command with your local run.

Verify: rerun the same build against the same commit and context in CI.

Fix #4 — verify multi-stage output

For COPY --from=builder /app/dist /usr/share/nginx/html, the source comes from the builder stage, not your host's context. Ensure the earlier build step actually creates /app/dist. If --from names a non-stage source, check that the command supplies the matching named context with the build-context option; otherwise BuildKit cannot read the host directory you expected.

docker build --target builder --progress=plain -t myapp:builder .

Inspect the resulting stage with an appropriate disposable container when possible. If the build emits /app/build instead, fix the producing command or destination after confirming the output.

Verify: the final-stage COPY --from now completes.

What not to do

Do not start with docker system prune -a, disable BuildKit, delete all ignore rules, or copy secrets into the image. These actions do not establish whether the missing source is in the correct context and can cause collateral damage.

Still failing? Capture this evidence

Before escalation, collect:Full error line and highlighted Dockerfile instructionExact docker build/buildx command and working directoryDockerfile path, build context and applicable ignore filesdocker version and docker buildx versionRelevant git ls-files output and local-vs-CI comparisonProducing stage output path for COPY --from failures

Redact tokens, private repository paths and credentials. If the same source remains absent after context and ignore verification, prepare a minimal reproducer for the Docker/BuildKit issue tracker.

Authoritative references

Ask the community

Share the redacted error line, build command and context layout; never share credentials or private source.

Loading community discussion…