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.

Introduction & Quick Summary
ERROR: failed to compute cache key: "/package.json" not found: not foundBuildKit 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 dockersendsdocker/as the context, not the project root. .dockerignoreexcludes it. A pattern such as*.json,**/node_modules, or a negation after a parent exclusion removes the path from the context.- The
COPYsource is relative to the context, not to the Dockerfile.COPY package.json .insidedocker/Dockerfilelooks for<context>/package.json. - The path climbs out of the context.
COPY ../shared/config.jsonis refused, because nothing above the context is shipped. - A stage name or case mismatch.
COPY --from=build /app/dist ./distfails when the stage isbuilder, and Linux paths are case sensitive.
| Message fragment | Meaning | Fix |
|---|---|---|
"/package.json" not found | Root of the context lacks the file | Correct the context or the path |
failed to calculate checksum of ref ...: not found | Same failure, newer BuildKit wording | Same |
forbidden path outside the build context | COPY ../x | Move the file or widen the context |
"/app/dist" not found after --from | Stage name or output path | Use the stage name as written |
| Works locally, fails in CI | CI checks out a different layout | Log 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:
# docker/Dockerfile
FROM node:22-alpine AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run builddocker build -f docker/Dockerfile docker -t app
# ERROR: failed to compute cache key: "/package.json" not found: not foundThe same command with the project root as the context succeeds, and it also makes COPY . . meaningful:
docker build -f docker/Dockerfile . -t app# see exactly what the builder receives, without building
docker build -f docker/Dockerfile . -t app --no-cache --progress=plainKey Comparison Table
The context argument is the single most common mistake, and its effect depends on how the Dockerfile writes its paths.
| Command | Context sent | COPY package.json finds | COPY docker/x finds |
|---|---|---|---|
docker build . | Project root | <root>/package.json | <root>/docker/x |
docker build docker | docker/ only | Not found | <root>/docker/docker/x |
docker build -f docker/Dockerfile . | Project root | <root>/package.json | <root>/docker/x |
docker build -f docker/Dockerfile docker | docker/ only | Not 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.
| Pattern | Effect | Can a later ! re-include? |
|---|---|---|
node_modules | Excludes the directory | Yes, with !node_modules/keep only if the parent is re-included |
**/*.json | Excludes every JSON file at any depth | Yes, with !package.json |
secrets/ then !secrets/public.pem | The parent exclusion wins | No |
!package.json alone | Re-includes a previously matched file | n/a |
.env* | Excludes all env files | No 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.
# 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 appThe 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.
# confirm the effective patterns from the context root
cat .dockerignore
docker build --progress=plain -f docker/Dockerfile . 2>&1 | grep -i "context\|transferring"# .dockerignore
node_modules
.git
**/*.log
# keep the manifests the build needs
!package.json
!package-lock.json
!tsconfig.jsonNegations 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.
# 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# 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/uiCopying 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.
FROM node:22-alpine AS builder
WORKDIR /app
COPY package.json ./
RUN npm ci && npm run build
FROM nginx:alpine
COPY /app/dist /usr/share/nginx/html # stage is "builder"COPY /app/dist /usr/share/nginx/htmlStage 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/Dockerfileservices:
web:
build:
context: .
dockerfile: docker/Dockerfile
args:
NODE_ENV: productionIf the context must stay narrow, copy the required files into it in a preliminary step, or use a named build context with BuildKit:
docker buildx build --build-context shared=../shared -f Dockerfile .COPY ./config/api.json ./config/api.jsonCase, symlinks and generated files
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.
# find the real case of a file the build needs
find . -maxdepth 2 -iname "package*.json" -printf "%p\n"# 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:
tar -cf - --exclude-from=.dockerignore . | tar -tf - | grep -E "package.json|src/" | headWhen 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 documentationThe Docker documentation that defines the behaviour this guide explains.
Try matching browser tools
All toolsSmall utilities that fit Docker work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Docker guides
All Docker guidesDocker: pull access denied, repository does not exist or may require login
The registry refused the pull for one of five reasons. Separate missing credentials from missing permission, wrong namespace and rate limits.
Docker Hub: toomanyrequests and the pull rate limit behind it
Shared CI addresses drain the anonymous quota. Log in, cache the bytes once, and stop pulling production images from Docker Hub.
Docker Compose: dependency failed to start and the health check behind it
The container named in the error is the failing one. Inspect its health log, choose the right condition, and give slow databases a start period.
Docker build: no space left on device while df shows free space
BuildKit cache lives outside docker system df. Measure it with buildx du, prune to a size budget and reorder the Dockerfile.
More in Docker
All Docker guidesThe guides filed next to this one in Docker, in library order.