Docker failed to calculate checksum of ref, in CI

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.

A 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.

The 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.

Another 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.

In 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.

To 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.