Docker

Docker "Failed to Compute Cache Key" Build Error

The "failed to compute cache key" error almost always means a COPY or ADD instruction in your Dockerfile references a file or path that doesn't actually exist in the build context — BuildKit can't hash something for caching purposes if the source path isn't there to begin with.

The Problem

A docker build fails partway through with an error like:

failed to compute cache key: "/app/dist" not found: not found
failed to solve: failed to compute cache key: failed to calculate checksum of ref: "/package.json": not found

The file referenced genuinely seems to exist when you look at the project directory, which makes the "not found" message confusing at first glance.

Why It Happens

This error is BuildKit (Docker's modern build engine) failing to locate a file it needs to copy into the image, for one of a few specific reasons:

  • A typo in the path specified in the COPY instruction, not matching the actual file or directory name exactly
  • The file exists on disk but is excluded from the build context by a .dockerignore rule, making it invisible to Docker even though it's genuinely present in the project folder
  • In a multi-stage build, referencing a path from an earlier stage that was never actually created in that stage — for example, expecting a build output directory that the build command in that stage didn't actually produce, due to a build failure or misconfiguration upstream
  • The build context itself doesn't include the directory containing the file, often because docker build was run from the wrong directory, or the Dockerfile's COPY instruction assumes a build context root different from what was actually specified

The Fix

First, confirm the exact path referenced in the failing COPY instruction matches the actual file location exactly, including case sensitivity:

COPY package.json ./
COPY dist/ ./dist/

Compare this directly against what actually exists using ls from the same directory your build context is rooted in:

ls -la package.json dist/

Check your .dockerignore file for a pattern that might be unintentionally excluding the file, since an ignored file behaves as if it doesn't exist from Docker's perspective, even while remaining fully visible in your normal file browser or editor:

cat .dockerignore

A broad pattern like dist/ in .dockerignore, added for a different reason (like keeping local build artifacts out of version control), can also accidentally exclude the exact directory a later build stage needs to copy from.

For multi-stage builds, confirm the earlier stage actually produced the expected output before the later stage tries to copy it. Build just that earlier stage in isolation to verify:

docker build --target build -t debug-stage .
docker run -it debug-stage ls -la /app/dist

If this shows the directory is missing or empty, the actual problem is upstream — the build command in that earlier stage isn't producing the output you expect, and fixing the COPY path in the later stage won't help until the earlier stage genuinely creates what it's supposed to.

Confirm you're running docker build from the correct directory, since the build context (and therefore what relative paths in COPY resolve against) is determined by the path argument passed to the build command, not necessarily where the Dockerfile itself lives:

docker build -t your-app .
# the "." here defines the build context root - confirm this is the directory
# you actually expect COPY paths to be relative to

Still Not Working?

If everything above checks out and the error persists, clear Docker's build cache entirely and retry, since a stale or corrupted cache state can occasionally produce confusing cache-key-related errors unrelated to the actual current state of your files:

docker builder prune -a
docker build --no-cache -t your-app .

If the issue only appears in a CI/CD environment and not locally, compare the exact build context being used in each — CI systems sometimes checkout code differently (shallow clones, different working directories, or .dockerignore handling that differs slightly between local Docker and the CI runner's Docker installation version) in ways that can produce a "file not found" error that never reproduces on a developer's own machine.

You might also like