Docker · Beginner · 12 min
Fix Docker COPY 'not found in build context'
Fix Docker COPY "failed to compute cache key: not found": list the real build context, then fix the path, the context or .dockerignore.
COPY can only use what the builder received. This runbook lists the real build context, explains why BuildKit prints the same message for a missing, ignored or outside file, and fixes each case without widening the context. Commands were run on Ubuntu 26.04 with Docker Engine 29.1.3, with BuildKit and the legacy builder.
On this page
See it run
A short replay of real output from commands in this guide, captured on a WSL2 Ubuntu test machine (Docker 29.1.3 with BuildKit (buildx 0.30.1)). The typing is replayed, and the host name, account and MAC addresses are redacted. Your output will differ, and a test machine is not a production server.
Text version of this demo
ops@web-01:~$ docker build -q -t ob-ctx . 2>&1 | grep -m1 -o 'failed to compute cache key.*' failed to compute cache key: failed to calculate checksum of ref 4a17fcss7exsmpo9z3j1p88ai::2frtvo5iekvp7qxulx1tow628: "/target/app.jar": not found ops@web-01:~$ printf 'FROM busybox:1.37\nCOPY . /ctx\nRUN find /ctx -type f | sort\n' | docker build --no-cache --progress=plain -f- . 2>&1 | grep -o '/ctx/.*' /ctx/.dockerignore /ctx/Dockerfile /ctx/config/app.conf ops@web-01:~$ cat .dockerignore target/ ops@web-01:~$ printf 'target/\n!target/app.jar\n' > .dockerignore && docker build -q -t ob-ctx . >/dev/null && docker run --rm ob-ctx ls /app/ app.jar
docker build does not read files from your disk while it builds. It first packs the build context, usually the folder you pass as the last argument (the . in docker build .), filters it through .dockerignore, and sends it to the builder. COPY and ADD can only use what is in that package. When a file is missing from it, BuildKit stops with failed to compute cache key: ... not found, and the legacy builder with COPY failed: file not found in build context. This runbook shows what the builder actually received and fixes the reason the file is not there.
Commands and output were captured on an Ubuntu 26.04 test machine with Docker Engine 29.1.3, using both BuildKit (buildx 0.30.1, the default builder) and the legacy builder (DOCKER_BUILDKIT=0).
0. Rules of engagement
- Do not widen the context to the whole disk or your home folder to make a file visible. Everything in the context is sent to the builder, and anything a
COPY . .picks up can end up in the image, including keys and.envfiles. - Do not delete
.dockerignoreto fix one file. It usually keeps secrets,node_modulesand build output out of the image. Add an exception instead (section 4). - Read the path in the message. It is relative to the context root, not to your current folder or to the Dockerfile.
1. Read the message
| What happened | BuildKit (default) | Legacy builder |
|---|---|---|
| The file is not in the context | failed to compute cache key: failed to calculate checksum of ref ...: "/app.jar": not found | COPY failed: file not found in build context or excluded by .dockerignore: stat app.jar: file does not exist |
.dockerignore excludes it | same as above: "/target/app.jar": not found | same as above |
The path points outside the context (../secret.txt) | same as above: "/secret.txt": not found | COPY failed: forbidden path outside the build context: ../secret.txt () |
| The context folder itself does not exist | ERROR: failed to build: unable to prepare context: path "nosuchdir" not found | unable to prepare context: path "nosuchdir" not found |
# Real output from the test machine (BuildKit): the same message for a missing file, an ignored file and a path outside the context
ERROR: failed to build: failed to solve: failed to compute cache key: failed to calculate checksum of ref 4a17fcss7exsmpo9z3j1p88ai::uc28hy59g7actgql3qxx06op3: "/app.jar": not foundWith BuildKit, the three common causes print the same line, so the next step is to look at the context itself. BuildKit also drops a leading ../ from the path, which is why ../secret.txt is reported as "/secret.txt": not found.
2. See what the builder receives
Build a throwaway image that copies the whole context and lists it. It uses your real .dockerignore:
# List every file in the build context after .dockerignore is applied (nothing is kept)
printf 'FROM busybox:1.37\nCOPY . /ctx\nRUN find /ctx -type f | sort\n' | docker build --no-cache --progress=plain -f- .# Real output from the test machine (trimmed): target/app.jar is missing because .dockerignore excludes target/
#7 0.503 /ctx/.dockerignore
#7 0.503 /ctx/Dockerfile.ignored
#7 0.503 /ctx/Dockerfile.missing
#7 0.503 /ctx/Dockerfile.outside
#7 0.503 /ctx/config/app.confRun it from the same folder and with the same last argument as your failing build. If the file is not in the list, the cause is one of sections 3 to 5.
3. The file is not in the context folder
- Wrong context argument.
docker build -f docker/Dockerfile docker/usesdocker/as the context, soCOPY src/ .looks fordocker/src/. Run the build from the project root withdocker build -f docker/Dockerfile .. - The file is created by a step you did not run.
target/app.jarexists only after the Java build. Either build it beforedocker build, or build it inside the image with a multi-stage Dockerfile. - Case and spelling. Linux paths are case-sensitive:
App.jaris notapp.jar, even if your Windows or macOS editor treats them the same. - Compose. In
docker-compose.yml,build.contextsets the context andbuild.dockerfileis relative to it. Acontext: ./apiwithCOPY ../shared .cannot work.
4. .dockerignore excludes it
# Patterns that may match the file; rules are applied top to bottom, the last match wins
cat .dockerignoreAdd an exception after the rule that excludes it, instead of removing the rule:
# .dockerignore: keep build output out, but send the one artifact the image needs
target/
!target/app.jarOn the test machine this exception worked with both BuildKit and the legacy builder: target/other.txt stayed out and target/app.jar was sent. Check the result with the listing from section 2, because the last matching rule wins and a later pattern can exclude the file again.
5. The path points outside the context
The builder cannot read anything above the context root; ../ paths are forbidden. Choose one:
- Move the context up to a folder that contains everything you need (for example the repository root), and keep secrets out with
.dockerignore. - Use a named build context (BuildKit):
docker build --build-context shared=../shared .andCOPY --from=shared config.yaml /etc/app/in the Dockerfile. - Copy the file in before the build in your script or CI job.
6. Verify
# The build succeeds and the file is where the application expects it
docker build -t app:test .
docker run --rm --entrypoint ls app:test -l /app/# Real output from the test machine after removing the .dockerignore rule
total 4
-rw-r--r-- 1 root root 4 Oct 30 23:06 app.jar7. Rollback and prevention
- Rollback: revert the Dockerfile,
.dockerignoreor build command change; nothing outside the build is touched. - Keep the context small and explicit, with a
.dockerignorethat excludes.git, secrets, local environment files and dependency folders. - Run
docker buildthe same way locally and in CI, from the same folder with the same arguments, so the context is the same. - Prefer multi-stage builds that produce the artifact inside the build, so the image does not depend on a file someone forgot to build.
References
Official reference
Technical steps are original explanations; consult the upstream documentation for version-specific details.
Behavior differs by distribution and tool version. Commands are examples for authorized systems; review output for secrets before sharing.
Found this useful?
Follow us on YouTube for video explainers, and find us on Facebook to keep up with what is new.