Docker: failed to compute cache key — "/file": not found

The exact error string

$ docker build -t myapp .
 => ERROR [4/8] COPY package.json ./
------
 > [4/8] COPY package.json ./:
------
failed to solve: failed to compute cache key: failed to calculate checksum
of ref abc123::xyz: "/package.json": not found

// The legacy (non-BuildKit) builder says the same thing far more plainly —
// and names the second-most-common cause outright:
//
// COPY failed: file not found in build context or excluded by .dockerignore:
// stat package.json: file does not exist

If Docker reports failed to compute cache key: failed to calculate checksum of ref … "/file": not found, the problem is almost always that the file isn't in the build context — not that anything is wrong with your cache. The wording is unhelpful in a specific way: it describes the step that failed (hashing a file to decide whether the layer can be reused) rather than the reason (the file isn't there to hash). Read past "cache key" — the useful part is the quoted path at the end and the COPY line above it. The legacy builder's message is the better mental model, because it names both causes at once: not in the build context, or excluded by .dockerignore.

The one concept that explains most of these

COPY source paths are resolved from the build context root — the path you pass as the final argument to docker build — and never from the directory the Dockerfile happens to live in. Only files inside that context are uploaded to the builder; everything else may as well not exist.

Everything on this page applies equally to ADD, which resolves local source paths the same way and fails with the same message.

Cause 1: the Dockerfile is in a subdirectory

The classic. Your Dockerfile sits in docker/ and its COPY lines are written as if paths were relative to itself:

# myrepo/docker/Dockerfile, built with:  docker build -f docker/Dockerfile .

# ❌ package.json sits beside the Dockerfile, in docker/
# COPY package.json ./

# ✅ spell it from the context root
COPY docker/package.json ./

The mirror-image mistake is just as common: the file is at the repo root, but you build with docker build docker/, which shrinks the context so the root file now sits outside it. Pick where the context root should be first, then write every path relative to that.

The same trap in Docker Compose

Compose splits the two settings across separate keys, which makes it easy to assume dockerfile: is what matters. It isn't — context: is:

services:
  app:
    build:
      context: .                      # ← this sets the COPY root
      dockerfile: docker/Dockerfile   # ← this only says which file to read

With that config, COPY package.json ./ looks for <project-root>/package.json, not <project-root>/docker/package.json — exactly as if you'd run docker build -f docker/Dockerfile . by hand. Note also that context: is relative to the Compose file's own location, so moving compose.yaml into a subdirectory silently moves the root along with it.

Cause 2: .dockerignore is excluding it

The most confusing version, because the file is plainly on disk and the path is plainly correct. Excluded files are never uploaded, so the build genuinely cannot see them:

# .dockerignore
*                    # exclude everything...
!src/                # ...then re-include only these
!package.json

# A Dockerfile line like `COPY tsconfig.json ./` now fails: tsconfig.json
# was excluded by `*` and never re-included.

Allowlist patterns (* followed by ! re-inclusions) cause this far more often than plain denylists, because adding a new file to the repo silently leaves it excluded — the build breaks on a file you never touched.

Three cheap checks, in order, before anything clever:

1. grep your .dockerignore for anything that could match the path — and read the whole file, since a later ! line may or may not re-include what an earlier rule excluded.
2. Confirm the context root you're actually building with (the final argument to docker build, or context: in Compose).
3. Re-read the COPY source character by character against the real path on disk.

Advanced: see exactly what the builder received. If those three don't settle it, build a throwaway image that copies the whole context and lists it — this reflects .dockerignore filtering precisely, with no guessing about pattern semantics:

# Print the context as the builder sees it, honouring .dockerignore
$ docker build --no-cache --progress=plain -f - . <<'EOF'
FROM busybox
COPY . /ctx
RUN find /ctx -maxdepth 2 -not -path '*/.git/*'
EOF

If the missing file doesn't appear in that listing, .dockerignore is your answer — no further guessing needed.

Cause 3: the path escapes the context with ..

Sharing a library between two services and reaching "up and over" into it is the natural instinct, and it can never work:

# ❌ from a context of ./service-a, this points outside — always fails
# COPY ../shared/lib ./lib

# ✅ move the context up so both are inside it, and keep -f pointing at the file
$ docker build -f service-a/Dockerfile -t service-a .
# then, in the Dockerfile:
COPY shared/lib ./lib
COPY service-a/src ./src

Widening the context has a cost worth knowing: everything inside it is uploaded to the builder on every build, so a repo-root context with large directories makes builds slow. Pair it with a .dockerignore that excludes node_modules, .git, build output, and anything else the image doesn't need — which is the same file that causes Cause 2, so keep the two in mind together.

Cause 4: the file isn't committed (CI-only failures)

Builds fine locally, fails on the runner. The usual explanation is that the file exists in your working tree but not in a fresh checkout:

# Is the path actually tracked by git?
$ git ls-files --error-unmatch dist/bundle.js
error: pathspec 'dist/bundle.js' did not match any file(s) known to git

Typical culprits are build output covered by .gitignore, a local .env, or generated code. The second flavour is ordering: a step that produces the file runs before docker build on your machine but after it in the pipeline. Either commit the file, generate it earlier in the pipeline, or produce it inside the Dockerfile so the build no longer depends on the host having run something first.

The third flavour is case. macOS and Windows filesystems are case-insensitive by default, so COPY Config.json ./ happily finds a file named config.json on your machine and fails on a case-sensitive Linux CI runner:

# Local (macOS/Windows): resolves — the filesystem ignores case
# CI (Linux):            "/Config.json": not found

$ git ls-files config.json
config.json          # ← tracked and present; the NAME is what's wrong

This one is worth calling out separately because it slips past the git ls-files check above: the file is committed and present, so that test passes while the build still fails. Compare the exact casing in the COPY line against git ls-files output, which reports the name as recorded in the repository rather than as your local filesystem chooses to display it.

Cause 5: COPY --from in a multi-stage build

Here the rules change: with --from, the source path resolves inside the named stage's filesystem, not the build context. So "not found" means that path doesn't exist in that stage:

FROM node:22-slim AS builder
WORKDIR /app
COPY . .
RUN npm ci && npm run build      # produces /app/dist

FROM node:22-slim
WORKDIR /app
# ❌ wrong path inside the builder stage — build output is at /app/dist
# COPY --from=builder /dist ./dist

# ✅
COPY --from=builder /app/dist ./dist

Three things to check when --from fails: the stage name is spelled the same as its AS label; the stage is typically defined earlier in the file (BuildKit does resolve forward references in some cases, but ordering the stages conventionally removes the question); and the build in that stage actually produced the directory you're naming. For the third, stop at the earlier stage and look:

# Build only the builder stage, then inspect what it really contains
$ docker build --target builder -t myapp-builder .
$ docker run --rm myapp-builder ls -la /app

That --target trick is the fastest way to settle a multi-stage disagreement, and it works for any stage in the file. If the stage itself fails to start rather than the copy, see executable file not found in $PATH.

Quick triage

Debugging checklist

• ✓ Read the quoted path and the COPY line above it — ignore the words "cache key"
• ✓ Identify your context root: the last argument to docker build, or context: in Compose
• ✓ Re-spell every COPY source relative to that root, not to the Dockerfile
• ✓ Search .dockerignore for a pattern matching the path — especially * allowlists
• ✓ List what the builder actually received (the COPY . /ctx + find trick above)
• ✓ Any .. in the source path? It can't escape the context — widen the context instead
• ✓ CI-only? git ls-files --error-unmatch <path> to confirm it's committed
• ✓ CI-only but the file is tracked? Check the filename's casing — Linux is case-sensitive, your laptop probably isn't
• ✓ On Compose? build.context sets the root; dockerfile: only picks the file
• ✓ Using --from? Check the stage name, its position in the file, and what it really produced
• ✓ Rerun with --progress=plain --no-cache for unabridged output

References

• Build context (Docker Docs)
• Dockerfile reference (Docker Docs)