Docker / Editorial solution guide

COPY source not found: inspect context before cache

Resolve build input boundaries, ignore rules, and case-sensitive paths without widening access or resetting a shared builder.

About 3 min readContent reviewed

Read-only knowledge base ยท No public comments

Recognize the symptoms

BuildKit reports a COPY source as not found or includes the diagnostic excerpt failed to calculate checksum. The exact step and source path matter; the excerpt alone does not prove cache corruption.

The Dockerfile appears next to the file on the developer machine, yet a remote or CI build cannot access it. A file can also exist locally while .dockerignore excludes it from the context.

Understand the likely causes

  • COPY sources are resolved from the selected context root, not automatically the Dockerfile directory. The final build argument chooses that root; -f chooses a recipe.
  • Wrong working directory, case differences, ignored generated files, or an uncreated artifact can each produce missing-input symptoms. Cache removal does not supply a file that was never sent.

Write down the exact directory boundary

Record the working directory, complete build command, Dockerfile path, context argument, and source path from the failing instruction. Do not collect unrelated secrets or recursively publish a home-directory listing. The following synthetic layout places the recipe under docker/ while keeping app.py at the context root. That layout is valid when the root is selected deliberately.

text Synthetic source layout 
parcel-lab/
  app.py
  .dockerignore
  docker/
    Dockerfile

The directory tree is declared teaching input, not an observed filesystem. COPY app.py refers to the root-level file when parcel-lab is the context. It does not refer to docker/app.py merely because the recipe resides under docker/.

Check presence, spelling, and ignore rules

Inspect the required relative file and the applicable .dockerignore rules. Compare app.py with App.py on the actual build filesystem. Check whether CI generates the file before the context is prepared and whether the job checked out the correct source revision. A parent traversal does not grant COPY access to arbitrary host files outside the context. Keep the intended boundary narrow instead of making an entire disk available to silence the error.

Align context and recipe without hiding inputs

For the declared layout, the following command selects the root context and a nested Dockerfile. It is a review-only build plan and is not executed. The Dockerfile should COPY app.py from that context, with other required fixture files declared explicitly. If a generated binary is intended, make generation an explicit build stage or supply the reviewed artifact through a documented pipeline input.

bash Correctly scoped build plan 
docker build --file docker/Dockerfile --tag parcel-api:lab .

The trailing dot, not -f, defines the source boundary. This command would perform a build and may contact a builder or registry if authorized later; it is not a read-only engine check and was not run here. No successful build id or timing is fabricated.

Distinguish a missing input from later failures

Once the source is included, another error may concern destination permissions, a missing executable, or application startup. Those require separate evidence. Preserve the original failing step and updated result instead of changing context, user, permissions, and cache simultaneously. Broad builder cleanup and copying secrets into the image are unrelated to restoring a missing declared source.

Verify the fix

Confirm every required source exists inside the resolved context after ignore filtering. In a separately authorized disposable environment, validate the complete recipe and compare its expected application artifact; this guide performs no build. Recheck CI using the same revision, context, and file options rather than accepting a local-only success.

Keep it from recurring

  • Document repository layout and build invocation together, keep .dockerignore reviewed, make generated artifacts explicit, and test representative CI contexts. Exclude credentials and avoid broad COPY rules unless their contents are intentionally part of the image.

Official references