ErrLookup › Background articles › Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them

Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them

Checksum mismatch, digest mismatch, or "checksum verification failed" errors appear when a library compares a hash (MD5, SHA-256, CRC32, CRC64ECMA, CRC32C) computed over data it just read, downloaded, or restored against an expected value recorded earlier — in a lockfile, a sidecar file, a release manifest, or a protocol trailer — and the two disagree. Developers hit this family when downloading release binaries and archives, restoring backups and snapshots, reading Hadoop files with .crc/.md5 sidecars, running distcp or pnpm installs, or streaming data between processes. A mismatch means the bytes in hand are not the bytes the checksum describes: corruption in transit or at rest, a stale or mismatched metadata file, configuration drift between the writer and reader, or — much more rarely — tampering.

Distilled from 100 documented records across 41 repositories.

Background

A checksum mismatch error is produced at an integrity-verification boundary: a point where a library deliberately compares a digest computed over bytes it now holds against a digest recorded when those bytes were written, published, or transferred. The comparison itself is trivial; everything interesting is in what the two sides represent. The expected value comes from somewhere else in time or space — a sidecar file next to the data (.crc files in Hadoop's ChecksumFileSystem, .md5 files verified by MD5FileUtils, SHA256SUMS in Nomad snapshots), a published manifest (Deno's upgrade .sha256 files, chezmoi's .chezmoiexternal checksum fields, Archon's checksums.txt, oh-my-pi's release manifest), a lockfile (pnpm's integrity field), a header captured earlier (the TOS connector's crc64ecma response headers), or a chained trailer in a log format (Turso's MVCC frames, waveterm's WriterChan final packet). The computed value is always fresh: the library hashes the exact bytes just read, downloaded, decrypted, or received.

The mechanisms cluster into a few shapes. Download verification is the most common: a tool streams an artifact, hashes it while streaming, and refuses to install if the digest differs from the pinned one (Deno's upgrade and laufey archives, oh-my-pi's binary digest check, Archon's web dist, ECC's release gate). Here the error is a supply-chain and transfer-integrity guard, and the bytes are usually discarded or deleted before the error propagates. At-rest verification is the second shape: storage systems recompute checksums chunk by chunk during reads — HDFS BlockSender re-CRCs each chunk against its .meta file, ChecksumFileSystem verifies 512-byte slices against the .crc sidecar — and throw with the exact failing offset, expected and computed values. These are corruption detectors, and libraries deliberately make them loud because retrying the same read keeps failing.

The third shape is protocol-level integrity: gokrazy echoes a CRC32 of bytes actually written to device storage so the Tailscale updater can compare against what it sent over HTTP; waveterm's WriterChan compares a sender-supplied SHA-256 against a locally computed running hash; Turso's MVCC log chains CRC32C from frame to frame so reordering or rewriting breaks the chain. In all three, a mismatch means bytes changed, dropped, duplicated, or arrived reordered between the two endpoints.

Finally, some mismatches are not corruption at all but comparability failures: Hadoop's MD5MD5CRC file checksum is only defined when every block used the same io.bytes.per.checksum, and its COMPOSITE_CRC mode tolerates varying chunk sizes but requires a single uniform CRC algorithm — so mixed-CRC files fail differently depending on combine mode. DistCp compares source and target checksums that are only comparable when block sizes, checksum types, and filesystem implementations line up (HDFS vs S3A). Puppet's filebucket goes furthest in interpretation: when two different byte sequences hash to the same requested digest, it suspects a hash collision (in practice, a caller overriding checksum_data) and raises rather than overwrite, deliberately omitting the path from the message. What the caller sees also varies: some errors name both digests (most), some name the file and offset (Hadoop), some include the download URL so a poisoned redirect is visible in logs (Deno's laufey check), and Deno's upgrade path even prints the Actual/Expected labels swapped — worth knowing before you trust which value is which.

Common causes

What usually fixes it

Go deeper

Documented occurrences

…and 80 more across the corpus — use search.

Honest provenance: generated on 2026-09-04 from AI-assisted analysis of the linked records. See how records are made.