{
  "id": "cicd/docker-buildkit-export-failed",
  "signature": "ERROR: failed to solve: failed to compute cache key: failed to calculate checksum of ref ...: not found",
  "signature_zh": "错误：无法解析：计算缓存键失败：无法计算引用的校验和...：未找到",
  "regex": "ERROR: failed to solve: failed to compute cache key: failed to calculate checksum of ref.*: not found",
  "domain": "cicd",
  "category": "build_error",
  "subcategory": null,
  "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.",
  "root_cause_type": "generic",
  "root_cause_zh": "Docker BuildKit 缓存导出失败，因为引用的缓存层丢失或损坏，通常是由于并发构建覆盖了相同的缓存或缓存上传不完整。",
  "versions": [
    {
      "version": "Docker 24.0.5",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "BuildKit 0.12.2",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Ubuntu 22.04",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "Rebuilding the entire Docker image without cache (--no-cache)",
      "why_fails": "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.",
      "fail_rate": 0.5,
      "condition": "",
      "sources": []
    },
    {
      "action": "Manually deleting all Docker cache directories on the runner",
      "why_fails": "Cache may be stored externally (e.g., on a registry or S3); local deletion doesn't fix remote cache corruption.",
      "fail_rate": 0.8,
      "condition": "",
      "sources": []
    },
    {
      "action": "Increasing the build timeout",
      "why_fails": "The error is not timeout-related; it's a cache integrity issue.",
      "fail_rate": 0.95,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "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 .",
      "success_rate": 0.85,
      "how": "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 .",
      "condition": "",
      "sources": []
    },
    {
      "action": "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} .",
      "success_rate": 0.9,
      "how": "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} .",
      "condition": "",
      "sources": []
    },
    {
      "action": "Clear the remote cache entirely: docker buildx rm mybuilder; docker buildx create --use --driver-opt network=host; then rebuild with fresh cache export.",
      "success_rate": 0.75,
      "how": "Clear the remote cache entirely: docker buildx rm mybuilder; docker buildx create --use --driver-opt network=host; then rebuild with fresh cache export.",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "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 .",
    "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} .",
    "Clear the remote cache entirely: docker buildx rm mybuilder; docker buildx create --use --driver-opt network=host; then rebuild with fresh cache export."
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://docs.docker.com/build/cache/",
  "official_doc_section": null,
  "error_code": "BUILDKIT_CACHE_KEY_ERROR",
  "verification_tier": "ai_generated",
  "confidence": 0.88,
  "fix_success_rate": 0.82,
  "resolvable": "true",
  "first_seen": "2023-08-20",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}