## TL;DR
This error means the COPY source path does not exist in the build context as sent: the file is missing, the path is wrong relative to the context root, or .dockerignore excluded it. Remember COPY paths are relative to the context root, not the Dockerfile's directory. List the context contents to see what the builder actually received.

## The query
```text
docker build "failed to compute cache key: not found": COPY path debugging
```

## Use this when
- COPY fails with cache key not found
- Files exist locally but the build cannot see them
- After restructuring repos or contexts
- .dockerignore was recently changed

## Not for when
- Dockerfile syntax errors
- ADD with URLs (different semantics)
- Permission errors on copied files

## Steps

### Step 1: Verify the path relative to the context root
Check the COPY source against the build context root, not the Dockerfile location. A Dockerfile in docker/ with COPY app/ fails when the context root has no app/ directory. Context root is what matters.
Expected output: the path resolved correctly against the context root, or the mismatch found.

### Step 2: Check .dockerignore
A file excluded by .dockerignore is invisible to the builder even though it exists on disk. Review the ignore patterns; negations and directory patterns are the usual culprits.
Expected output: the file confirmed present in the sent context, or the ignore rule fixed.

### Step 3: List what the context actually contains
Inspect the files the build receives. The gap between "files on my laptop" and "files in the context" is the entire bug class. Confirm the expected file is in the sent set.
Expected output: the context contents known, not assumed.

### Step 4: Fix the COPY source or the context
Either correct the COPY path, adjust .dockerignore, or change the build context root passed to the build command. Pick the fix that matches the project's layout conventions.
Expected output: the COPY resolving to a real file in the context.

### Step 5: Pin the context in CI
CI checkouts with sparse paths or subdirectories change what the context contains vs local builds. Make the CI build pass the same context root as local builds, explicitly.
Expected output: local and CI builds seeing the same context.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_RZJXOPr2w1Fm-pS1-_NYrA