🚨 Docker Error Guide: 'failed to compute cache key: not found' — Fix Missing COPY/ADD Source Paths

Overview

BuildKit fails while resolving a COPY or ADD instruction because the source path it needs to hash does not exist inside the build context:

failed to compute cache key: "/app/package.json" not found: not found

To cache a COPY, BuildKit fingerprints the source files. If the path is absent from the context, there is nothing to fingerprint, so the build stops before copying. The message names the exact path it could not find.

Symptoms

• The build runs until a COPY or ADD step, then fails with failed to compute cache key.
• The named path looks correct in the Dockerfile but is missing from the sent context.
• The build works on one machine and fails on another (different working directory or checkout).
• The path exists on disk but is excluded by .dockerignore.

Common Root Causes

• Wrong build context — running docker build from a directory that does not contain the source path, so it is never sent to the daemon.
• .dockerignore exclusion — a pattern like * or node_modules silently drops the file from the context.
• Path is relative to context, not the Dockerfile — COPY sources are resolved against the build context root, not the Dockerfile’s location.
• Typo or wrong case — COPY Package.json when the file is package.json (case matters on the daemon’s filesystem).
• File is generated later — copying a build artifact that has not been produced yet.
• Multi-stage --from target — copying from a stage or image where the path does not exist.

Diagnostic Workflow

Confirm which directory you are building from and what the Dockerfile expects:

pwd
grep -nE '^(COPY|ADD)' Dockerfile

Verify the file actually exists at the path relative to the context root:

ls -l ./app/package.json

Check whether .dockerignore is excluding it — BuildKit honours these patterns when assembling the context:

cat .dockerignore

Re-run the build with a plain progress log so you can see the failing step and its resolved source:

docker build --progress=plain -t myapp:1.4.2 .

If you pass an explicit context and Dockerfile, make sure the context (last argument) is the directory that holds the source files:

docker build -f docker/Dockerfile -t myapp:1.4.2 .

For COPY --from=builder, inspect that stage’s filesystem by targeting and running it:

docker build --target builder -t myapp-builder:1.4.2 .
docker run --rm myapp-builder:1.4.2 ls -l /app

Example Root Cause Analysis

A pipeline copied a compiled binary and failed:

failed to compute cache key: "/dist/server" not found: not found

The Dockerfile had:

COPY dist/server /usr/local/bin/server

cat .dockerignore revealed:

dist/

An earlier optimization added dist/ to .dockerignore to keep local builds small, which stripped the compiled binary out of the context sent to the daemon. Because BuildKit never received dist/server, it could not compute a cache key for the COPY. Removing that line from .dockerignore (the binary is built inside the image, or should be included) fixed the build. The general rule: if the path exists on disk but the build cannot find it, suspect .dockerignore first.

Prevention Best Practices

• Always run docker build from the repository root and pass . as the context, so relative COPY paths resolve predictably.
• Review .dockerignore whenever a COPY fails — exclusions are the most common hidden cause.
• Reference COPY sources relative to the context root, never relative to the Dockerfile’s subdirectory.
• Keep source paths lowercase and consistent to avoid case-sensitivity surprises between macOS and Linux daemons.
• Lint Dockerfiles with the Dockerfile validator so obvious path and instruction mistakes surface before a build agent runs them.

Quick Command Reference

pwd                                      # confirm the build context directory
grep -nE '^(COPY|ADD)' Dockerfile        # list source paths the build needs
ls -l ./path/to/source                   # verify the file exists in context
cat .dockerignore                        # check for exclusions
docker build --progress=plain -t myapp:1.4.2 .
docker build --target builder -t myapp-builder:1.4.2 .

Conclusion

failed to compute cache key: not found is BuildKit telling you a COPY/ADD source is missing from the context it received — not necessarily missing from disk. Check the build context directory, then .dockerignore, then the exact path and case. Building from the repo root with a clear .dockerignore prevents almost every occurrence. Find more build fixes in the Docker stack guides.