# failed to solve: failed to compute cache key: failed to calculate checksum of ref

- **ID:** `docker/buildkit-cache-key-failed`
- **Domain:** docker
- **Category:** build_error
- **Verification:** ai_generated
- **Fix Rate:** 90%

## Root Cause

BuildKit failed to compute cache keys, usually because a COPY/ADD source path doesn't exist in the build context or is excluded by .dockerignore. Also occurs with corrupt BuildKit cache.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| 27 | active | — | — |

## Workarounds

1. **Check .dockerignore to ensure required files are not excluded** (88% success)
   ```
   cat .dockerignore
# Make sure the file referenced in COPY is not matched by any pattern.
# Common mistake: ignoring 'node_modules' also ignores 'node_modules/.package-lock.json' needed for npm ci
   ```
2. **Verify the build context includes the file and COPY path is relative to context root** (90% success)
   ```
   # List files in build context:
docker build --progress=plain . 2>&1 | head
# COPY paths are relative to the build context, NOT the Dockerfile location.
# Use: COPY ./src ./app/src (relative to context root)
   ```
3. **Clear corrupt BuildKit cache** (85% success)
   ```
   docker builder prune --all --force
# Or remove BuildKit cache directory:
# rm -rf ~/.local/share/docker/buildkit/
   ```

## Dead Ends

- **Running docker build with --no-cache to bypass the issue** — If the source file genuinely doesn't exist in the build context, skipping cache doesn't help. The COPY instruction will still fail. (70% fail)
- **Switching from BuildKit to legacy builder** — Legacy builder is deprecated and will be removed. It may give a different error message but the underlying issue (missing files) remains. (80% fail)