# ERROR: failed to solve: failed to compute cache key: failed to calculate checksum of ref ...: not found

- **ID:** `cicd/docker-buildkit-export-failed`
- **Domain:** cicd
- **Category:** build_error
- **Error Code:** `BUILDKIT_CACHE_KEY_ERROR`
- **Verification:** ai_generated
- **Fix Rate:** 82%

## Root Cause

Docker BuildKit cache export fails because the referenced cache layer is missing or corrupted, often due to concurrent builds overwriting the same cache or incomplete cache uploads.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| Docker 24.0.5 | active | — | — |
| BuildKit 0.12.2 | active | — | — |
| Ubuntu 22.04 | active | — | — |

## Workarounds

1. **Invalidate the specific cache key by adding a unique build argument: docker build --build-arg BUILDKIT_INLINE_CACHE=1 --cache-from type=registry,ref=mycache --cache-to type=registry,ref=mycache,mode=max .** (85% success)
   ```
   Invalidate the specific cache key by adding a unique build argument: docker build --build-arg BUILDKIT_INLINE_CACHE=1 --cache-from type=registry,ref=mycache --cache-to type=registry,ref=mycache,mode=max .
   ```
2. **Use a unique cache tag per build (e.g., cache-<commit-sha>) to avoid collision: docker build --cache-from type=registry,ref=myrepo/cache:${GITHUB_SHA} --cache-to type=registry,ref=myrepo/cache:${GITHUB_SHA} .** (90% success)
   ```
   Use a unique cache tag per build (e.g., cache-<commit-sha>) to avoid collision: docker build --cache-from type=registry,ref=myrepo/cache:${GITHUB_SHA} --cache-to type=registry,ref=myrepo/cache:${GITHUB_SHA} .
   ```
3. **Clear the remote cache entirely: docker buildx rm mybuilder; docker buildx create --use --driver-opt network=host; then rebuild with fresh cache export.** (75% success)
   ```
   Clear the remote cache entirely: docker buildx rm mybuilder; docker buildx create --use --driver-opt network=host; then rebuild with fresh cache export.
   ```

## Dead Ends

- **Rebuilding the entire Docker image without cache (--no-cache)** — While this bypasses the cache key error, it defeats the purpose of caching and significantly increases build time; the underlying cache corruption is not fixed. (50% fail)
- **Manually deleting all Docker cache directories on the runner** — Cache may be stored externally (e.g., on a registry or S3); local deletion doesn't fix remote cache corruption. (80% fail)
- **Increasing the build timeout** — The error is not timeout-related; it's a cache integrity issue. (95% fail)