Docker "failed to compute cache key: not found" in CI

By Daniel Zoghalchali·Latchkey

BuildKit hashes the files a COPY/ADD references to compute its cache key. When a referenced path is absent from the build context, there is nothing to hash and the build fails before running the step.

What this error means

A docker build fails on a COPY/ADD line with failed to compute cache key: failed to calculate checksum of ref ...: "/path": not found. It is deterministic for a given context.

docker

------
 > [stage-1 3/7] COPY package.json package-lock.json ./:
------
ERROR: failed to solve: failed to compute cache key: failed to calculate checksum of ref abc123: "/package-lock.json": not found

Diagnose it: build context, cache, or platform?

A Dockerfile that builds locally and fails in CI usually differs in one of three ways: the build context contains different files, the layer cache is cold or poisoned, or the runner architecture does not match what the base image provides.

Terminal

# what is actually being sent as build context (dockerignore applies)
docker build --no-cache --progress=plain -t probe . 2>&1 | head -40

# what platform are you on, and what does the base image support?
docker version --format '{{.Server.Arch}}'
docker buildx imagetools inspect <base-image> | grep -i platform

# prove it is not a cache artefact
docker build --no-cache .

Common causes

Source path not in the build context

The file or directory named in COPY does not exist relative to the build context root passed to docker build.

Path excluded by .dockerignore

A .dockerignore pattern removed the file from the context, so COPY cannot see it.

Wrong build context directory

The build was invoked with a context (the trailing path or CI working-directory) that does not contain the expected files.

How to fix it

Confirm the path and context

List the build context to verify the file is present where COPY expects it.
Check COPY paths are relative to the context root, not the Dockerfile location.

Terminal

docker build -f Dockerfile -t app .
ls -la package-lock.json

Fix .dockerignore exclusions

Ensure no .dockerignore pattern excludes a file you COPY.
Re-include needed paths with a negation pattern if necessary.

.dockerignore

# .dockerignore
node_modules
!package-lock.json

Keep the build context small and deterministic

A missing .dockerignore sends node_modules, .git, and build output to the daemon, which is slow and can change layer hashes between environments.
A COPY of a path that exists locally but is gitignored will fail in CI, because the runner only has what the checkout produced.
Multi-arch builds need buildx and QEMU set up explicitly; a plain docker build on an ARM runner silently produces an ARM image.

How to prevent it

Keep COPY paths relative to the build context root, audit .dockerignore against everything the Dockerfile copies, and set the correct context/working-directory in CI.

Frequently asked questions

What causes Docker "failed to compute cache key: not found" in CI?

There are 3 common causes: source path not in the build context, path excluded by .dockerignore, and wrong build context directory. The file or directory named in COPY does not exist relative to the build context root passed to docker build.

How do I fix Docker "failed to compute cache key: not found" in CI?

There are 2 fixes depending on which cause you have: confirm the path and context and fix .dockerignore exclusions. Work through them in order, since the first is the most common.

What does Docker "failed to compute cache key: not found" in CI actually mean?

A docker build fails on a COPY/ADD line with failed to compute cache key: failed to calculate checksum of ref ...: "/path": not found.

How do I stop Docker "failed to compute cache key: not found" in CI happening again?

Keep COPY paths relative to the build context root, audit .dockerignore against everything the Dockerfile copies, and set the correct context/working-directory in CI.