Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Docker build: failed to compute cache key: not found

BuildKit cannot hash a file that is not in the context. Correct the context path, the .dockerignore rules, or the COPY source and stage name.

~5 min readDocker
#Docker#BuildKit#CI#Troubleshooting
A build context tray with a missing manifest slot, amber cache key lock and cyan copy arrow into the container

Introduction & Quick Summary

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

BuildKit cannot hash a file that is not in the build context, so it cannot compute the cache key for the COPY or ADD instruction. The build stops before running anything. The file almost always exists on disk; what is missing is the file inside the context that was sent to the builder.

The five reasons, in the order worth checking:

  • The context is the wrong directory. docker build -f docker/Dockerfile docker sends docker/ as the context, not the project root.
  • .dockerignore excludes it. A pattern such as *.json, **/node_modules, or a negation after a parent exclusion removes the path from the context.
  • The COPY source is relative to the context, not to the Dockerfile. COPY package.json . inside docker/Dockerfile looks for <context>/package.json.
  • The path climbs out of the context. COPY ../shared/config.json is refused, because nothing above the context is shipped.
  • A stage name or case mismatch. COPY --from=build /app/dist ./dist fails when the stage is builder, and Linux paths are case sensitive.
Message fragmentMeaningFix
"/package.json" not foundRoot of the context lacks the fileCorrect the context or the path
failed to calculate checksum of ref ...: not foundSame failure, newer BuildKit wordingSame
forbidden path outside the build contextCOPY ../xMove the file or widen the context
"/app/dist" not found after --fromStage name or output pathUse the stage name as written
Works locally, fails in CICI checks out a different layoutLog the context contents

Core Mechanics, Signatures & Reproducible Setup

BuildKit resolves every COPY source against the context root and hashes the matched files to build a cache key. A missing path is a hard error, not a warning, because the instruction's result cannot be defined without the input. The Dockerfile's own location does not affect resolution; only the context does.

A reproduction is two files and one build:

dockerfile
# docker/Dockerfile FROM node:22-alpine AS build WORKDIR /app COPY package.json package-lock.json ./ RUN npm ci COPY . . RUN npm run build
bash
docker build -f docker/Dockerfile docker -t app # ERROR: failed to compute cache key: "/package.json" not found: not found

The same command with the project root as the context succeeds, and it also makes COPY . . meaningful:

bash
docker build -f docker/Dockerfile . -t app
bash
# see exactly what the builder receives, without building docker build -f docker/Dockerfile . -t app --no-cache --progress=plain

Key Comparison Table

The context argument is the single most common mistake, and its effect depends on how the Dockerfile writes its paths.

CommandContext sentCOPY package.json findsCOPY docker/x finds
docker build .Project root<root>/package.json<root>/docker/x
docker build dockerdocker/ onlyNot found<root>/docker/docker/x
docker build -f docker/Dockerfile .Project root<root>/package.json<root>/docker/x
docker build -f docker/Dockerfile dockerdocker/ onlyNot found<root>/docker/x
Compose build: { context: ., dockerfile: docker/Dockerfile }Project root<root>/package.json<root>/docker/x

.dockerignore interacts with negation in a way that surprises people: a file cannot be re-included when its parent directory was excluded.

PatternEffectCan a later ! re-include?
node_modulesExcludes the directoryYes, with !node_modules/keep only if the parent is re-included
**/*.jsonExcludes every JSON file at any depthYes, with !package.json
secrets/ then !secrets/public.pemThe parent exclusion winsNo
!package.json aloneRe-includes a previously matched filen/a
.env*Excludes all env filesNo build secrets via context

Practical Edge Cases, Error Fixes & Deep Dive Code Examples

Put the Dockerfile outside the build root deliberately

When the Dockerfile lives in a subdirectory, either widen the context or copy the build files into the context first. Widening is simpler; a COPY of the Dockerfile itself is unnecessary.

bash
# widen: context is the project root docker build -f docker/Dockerfile . # narrow: context is a prepared staging directory rsync -a --exclude node_modules --exclude .git ./ build-context/ cp docker/Dockerfile build-context/Dockerfile docker build build-context -t app

The narrow form is worth it for large repositories, because the context upload is what makes builds slow. A .dockerignore at the context root achieves the same with less machinery.

Read .dockerignore from the context root

The ignore file is read from the context root, not from the Dockerfile's directory. Two ignore files, one next to the Dockerfile and one at the root, is a common reason a file disappears only in CI.

bash
# confirm the effective patterns from the context root cat .dockerignore docker build --progress=plain -f docker/Dockerfile . 2>&1 | grep -i "context\|transferring"
text
# .dockerignore node_modules .git **/*.log # keep the manifests the build needs !package.json !package-lock.json !tsconfig.json

Negations must come after the broad pattern and must not contradict an excluded parent directory.

Point at the file the context actually contains

A monorepo root context contains apps/web/package.json, so a Dockerfile that copies package.json fails until the path matches.

dockerfile
# monorepo-aware FROM node:22-alpine AS build WORKDIR /app COPY apps/web/package.json apps/web/package-lock.json ./ RUN npm ci COPY apps/web ./ RUN npm run build
dockerfile
# alternatives when workspace packages must be built too COPY package.json package-lock.json ./ COPY apps/web/package.json ./apps/web/ COPY packages/ui/package.json ./packages/ui/ RUN npm ci --workspace apps/web --include-workspace-root COPY apps/web ./apps/web COPY packages/ui ./packages/ui

Copying manifests before sources is what keeps the dependency layer cached; copying everything first defeats the cache even when it builds.

Named stages and COPY --from

A stage that was renamed but not updated in --from fails with the same cache-key error, pointing at the path inside the missing stage.

dockerfile
FROM node:22-alpine AS builder WORKDIR /app COPY package.json ./ RUN npm ci && npm run build FROM nginx:alpine COPY --from=build /app/dist /usr/share/nginx/html # stage is "builder"
dockerfile
COPY --from=builder /app/dist /usr/share/nginx/html

Stage names are case sensitive and refer to stages defined earlier in the same file. COPY --from=0 still works by index, but a reordering makes it wrong, so named stages are safer.

Build contexts in Compose

Compose resolves the context from the compose file's directory, and a relative Dockerfile path from the same directory. A context: docker with dockerfile: Dockerfile sends only docker/, which is the classic Compose version of this failure.

services: web: build: context: . dockerfile: docker/Dockerfile
services: web: build: context: . dockerfile: docker/Dockerfile args: NODE_ENV: production

If the context must stay narrow, copy the required files into it in a preliminary step, or use a named build context with BuildKit:

bash
docker buildx build --build-context shared=../shared -f Dockerfile .
dockerfile
COPY --from=shared ./config/api.json ./config/api.json

Linux contexts treat Package.json and package.json as different entries, and a symlink to a file outside the context is not followed by default.

bash
# find the real case of a file the build needs find . -maxdepth 2 -iname "package*.json" -printf "%p\n"
dockerfile
# follow symlinks: ship the target too, or copy the resolved content COPY config/ ./config/

Generated files, such as a lockfile created by a prebuild script, do not exist in the context because the context is captured before the build starts. Generate them on the host or inside a stage that does not need the file from the context.

Common Compilation/Runtime Mistakes & Version Gotchas

Deleting node_modules in the hope it is a cache issue. The context is captured before any cache is consulted, so a missing file is a path problem, not a cache problem. --no-cache changes nothing here.

COPY . . as the first line. It works but rebuilds dependency installation on every source change, and it also makes ignore mistakes invisible: a file that should be excluded is present, so nothing fails until the image is inspected.

Assuming --from copies from the host. It copies from another stage or an image. Host files must enter through the context.

Ignoring the transfer line. --progress=plain prints the context size and transfer time; a context of several gigabytes almost always means .git or node_modules is being sent, which is both slow and a source of accidental matches.

Version notes. The classic builder reports failed to compute cache key with a leading ERROR:, BuildKit reports failed to solve: failed to compute cache key and may add failed to calculate checksum of ref. BuildKit is the default since Docker 23, so older CI images show the classic wording for the same cause. --build-context requires Buildx; COPY --link changes cache behaviour but not path resolution.

Fix order: print the resolved context with --progress=plain, list what is actually in it, then correct the path or the ignore file. A tar of the context is a quick way to see the truth:

bash
tar -cf - --exclude-from=.dockerignore . | tar -tf - | grep -E "package.json|src/" | head

When you compare a working Dockerfile with a failing one, the text diff makes the path change obvious, and the Compose validator catches a context or dockerfile field that points at the wrong directory before the build starts.

Official references: Build cache invalidation and Build context.

Official references

primary documentation

The Docker documentation that defines the behaviour this guide explains.

Try matching browser tools

All tools

Small utilities that fit Docker work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Docker guides

More in Docker

All Docker guides

The guides filed next to this one in Docker, in library order.