{
  "id": 20140587,
  "title": "Docker failed to calculate checksum of ref, in CI",
  "url": "https://urgent.news/2026/11/15/docker-failed-to-calculate-checksum-of-ref-in-ci",
  "topic": "tech",
  "section": "Tech",
  "published": "2026-11-15T08:13:32.000Z",
  "source": {
    "name": "Dev.to",
    "slug": "dev-to",
    "url": "https://dev.to/kalemi/docker-failed-to-calculate-checksum-of-ref-in-ci-324k"
  },
  "original_language": "en",
  "account": "When Docker attempts to compute a checksum for a content reference during a build, it can fail if it encounters a path that cannot be read. This error message, \"failed to calculate checksum of ref,\" is emitted by BuildKit when the referenced path is missing from the context, excluded by an ignore file, or resolved against an unexpected root. Searching for this error can be difficult because BuildKit does not emit any other sentences about the issue.\n\nA build failure occurs when there is a problem with a COPY or ADD command, and the message contains a long, opaque identifier in the middle along with a quoted path at the end. The identifier changes with every run, making the failure appear non-deterministic even though it is completely deterministic. Due to this, people often search for a half-remembered phrase and find no results, leading to wasted time.\n\nThe most common cause of this error is that the path is not part of the tree being hashed. This is usually due to the path being absent from the context, excluded by an ignore file, or resolved against an unexpected root. When searching for the error, remove the leading slash from the quoted path and list it to determine if it is a missing file or the wrong root.\n\nAnother possible cause is that the tree being hashed is a stage, not the context. When a `COPY --from` or a bind mount from another stage is used, it hashes that stage's filesystem. If the quoted path appears to exist only within a builder image, it is a stage and checking the repository will not help. Check which stage the failing line reads from first.\n\nIn rare cases, the file may have been removed mid-build, which can be caused by a background job, test suite writing to the context directory, or a cache restore racing the build. This failure is uncommon and does not reproduce on a rerun of the identical commit. The fix involves adjusting the sequencing rather than modifying the Dockerfile.\n\nTo prevent this error, sequence every step that writes into the build context before the build, never alongside it. Exclude generated directories to ensure the builder never hashes a tree that is still changing. When searching for build errors, focus on the longest alphabetic fragment of the error message, not the entire line. If quoting an error in your own documentation, copy it directly from a terminal rather than relying on memory.",
  "summary": "Docker failed to calculate checksum of ref is BuildKit naming the content reference it was hashing when a path under it could not be read. Two nearby sentences that circulate widely, the compute variant of this one and a claim about a file changing during the build, are not produced by any Docker component, and searching for them is why this failure is so hard to research. BuildKit emits \"failed…",
  "key_points": [
    "Docker fails to calculate checksum of ref during build",
    "Error occurs when referenced path is missing or excluded",
    "Check error message for path to identify missing file or stage"
  ],
  "editors_take": "The opaque and non-deterministic nature of BuildKit error messages forces developers to abandon standard search patterns in favor of isolating specific file fragments to resolve context mismatches.",
  "illustration": null,
  "coverage": {
    "outlets": 1,
    "also_reported_by": []
  },
  "ai_generated": true,
  "disclaimer": "Summaries, key points and the editor’s take are written by software from other outlets’ reporting and may contain errors — always check the linked original."
}