We earn commissions when you shop through the links below, at no extra cost to you. Our guides and technical recommendations are written independently of these relationships: a commission never decides what we recommend, how we diagnose a problem or what we publish, and the content does not depend on it. Affiliate disclosure

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.

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).

What COPY can see during a build1. docker build CONTEXT (the context folder is sent to the builder (section 3)) Then 2. .dockerignore (removes matching files from the context (section 4)) Then 3. COPY SRC DEST (SRC is read from the context only; ../ is forbidden (section 5)) Then 4. Not found (the same message for all three causes) ["/app.jar": not found].docker buildCONTEXTthe context folder issent to the builder(section 3).dockerignoreremoves matchingfiles from thecontext (section 4)COPY SRC DESTSRC is read from thecontext only; ../ isforbidden (section 5)Not foundthe same message forall three causes"/app.jar": not found
COPY reads only from the build context after .dockerignore has removed files from it. A missing file, an ignored file and a path outside the context all give the same BuildKit message.

0. Rules of engagement

  1. 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 .env files.
  2. Do not delete .dockerignore to fix one file. It usually keeps secrets, node_modules and build output out of the image. Add an exception instead (section 4).
  3. 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 happenedBuildKit (default)Legacy builder
The file is not in the contextfailed to compute cache key: failed to calculate checksum of ref ...: "/app.jar": not foundCOPY failed: file not found in build context or excluded by .dockerignore: stat app.jar: file does not exist
.dockerignore excludes itsame as above: "/target/app.jar": not foundsame as above
The path points outside the context (../secret.txt)same as above: "/secret.txt": not foundCOPY failed: forbidden path outside the build context: ../secret.txt ()
The context folder itself does not existERROR: failed to build: unable to prepare context: path "nosuchdir" not foundunable 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 found

With 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.conf

Run 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/ uses docker/ as the context, so COPY src/ . looks for docker/src/. Run the build from the project root with docker build -f docker/Dockerfile ..
  • The file is created by a step you did not run. target/app.jar exists only after the Java build. Either build it before docker build, or build it inside the image with a multi-stage Dockerfile.
  • Case and spelling. Linux paths are case-sensitive: App.jar is not app.jar, even if your Windows or macOS editor treats them the same.
  • Compose. In docker-compose.yml, build.context sets the context and build.dockerfile is relative to it. A context: ./api with COPY ../shared . cannot work.

4. .dockerignore excludes it

# Patterns that may match the file; rules are applied top to bottom, the last match wins
cat .dockerignore

Add 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.jar

On 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 . and COPY --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.jar

7. Rollback and prevention

  • Rollback: revert the Dockerfile, .dockerignore or build command change; nothing outside the build is touched.
  • Keep the context small and explicit, with a .dockerignore that excludes .git, secrets, local environment files and dependency folders.
  • Run docker build the 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

docs.docker.com ↗

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.