# failed to solve: failed to compute cache key: failed to calculate checksum of ref 'cache-mount-target': not found

- **ID:** `cicd/docker-buildkit-cache-mount`
- **Domain:** cicd
- **Category:** build_error
- **Error Code:** `BUILDKIT_CACHE_MOUNT_NOT_FOUND`
- **Verification:** ai_generated
- **Fix Rate:** 90%

## Root Cause

Docker BuildKit cache mount target directory does not exist in the build context or base image, causing checksum calculation to fail when using `--mount=type=cache,target=/path` in a Dockerfile.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| Docker 25.0 | active | — | — |
| BuildKit 0.12.0 | active | — | — |

## Workarounds

1. **Create the target directory in the Dockerfile before the cache mount is used: add `RUN mkdir -p /var/cache/apt` before the RUN instruction that uses `--mount=type=cache,target=/var/cache/apt`** (95% success)
   ```
   Create the target directory in the Dockerfile before the cache mount is used: add `RUN mkdir -p /var/cache/apt` before the RUN instruction that uses `--mount=type=cache,target=/var/cache/apt`
   ```
2. **Use a different base image that already contains the cache directory, or ensure the directory is included in the build context by creating it locally before build** (85% success)
   ```
   Use a different base image that already contains the cache directory, or ensure the directory is included in the build context by creating it locally before build
   ```

## Dead Ends

- **** — Removing the cache mount will break the build if the cache is required for package downloads (e.g., apt, npm); the build may fail due to network timeouts or missing dependencies (70% fail)
- **** — Disabling BuildKit removes cache mount support entirely, and the legacy builder may not support the same Dockerfile syntax, causing a different error (50% fail)