{
  "id": "docker/buildkit-cache-key-failed",
  "signature": "failed to solve: failed to compute cache key: failed to calculate checksum of ref",
  "signature_zh": "",
  "regex": "failed to compute cache key.*failed to calculate checksum",
  "domain": "docker",
  "category": "build_error",
  "subcategory": null,
  "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.",
  "root_cause_type": "generic",
  "root_cause_zh": "",
  "versions": [
    {
      "version": "27",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "Running docker build with --no-cache to bypass the issue",
      "why_fails": "If the source file genuinely doesn't exist in the build context, skipping cache doesn't help. The COPY instruction will still fail.",
      "fail_rate": 0.7,
      "condition": "File is missing from context",
      "sources": [
        "https://docs.docker.com/build/building/cache/"
      ]
    },
    {
      "action": "Switching from BuildKit to legacy builder",
      "why_fails": "Legacy builder is deprecated and will be removed. It may give a different error message but the underlying issue (missing files) remains.",
      "fail_rate": 0.8,
      "condition": "",
      "sources": [
        "https://docs.docker.com/reference/cli/docker/"
      ]
    }
  ],
  "workarounds": [
    {
      "action": "Check .dockerignore to ensure required files are not excluded",
      "success_rate": 0.88,
      "how": "cat .dockerignore\n# Make sure the file referenced in COPY is not matched by any pattern.\n# Common mistake: ignoring 'node_modules' also ignores 'node_modules/.package-lock.json' needed for npm ci",
      "condition": "",
      "sources": [
        "https://docs.docker.com/build/building/context/#dockerignore-files"
      ]
    },
    {
      "action": "Verify the build context includes the file and COPY path is relative to context root",
      "success_rate": 0.9,
      "how": "# List files in build context:\ndocker build --progress=plain . 2>&1 | head\n# COPY paths are relative to the build context, NOT the Dockerfile location.\n# Use: COPY ./src ./app/src (relative to context root)",
      "condition": "",
      "sources": [
        "https://docs.docker.com/build/building/context/"
      ]
    },
    {
      "action": "Clear corrupt BuildKit cache",
      "success_rate": 0.85,
      "how": "docker builder prune --all --force\n# Or remove BuildKit cache directory:\n# rm -rf ~/.local/share/docker/buildkit/",
      "condition": "Cache corruption after interrupted builds",
      "sources": [
        "https://docs.docker.com/build/cache/"
      ]
    }
  ],
  "workarounds_zh": [],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": [
      "docker/copy-failed-stat/docker27-linux"
    ]
  },
  "official_doc_url": null,
  "official_doc_section": null,
  "error_code": null,
  "verification_tier": "ai_generated",
  "confidence": 0.88,
  "fix_success_rate": 0.9,
  "resolvable": "true",
  "first_seen": "2022-01-01",
  "last_confirmed": "2026-02-14",
  "last_updated": "2026-02-14",
  "evidence_count": 95,
  "tags": [],
  "locale": "en",
  "aliases": [
    "docker/buildkit-cache-key-failed/docker27-linux"
  ]
}