jdx/mise · critical

Checksum mismatch for file {}: Expected: {algo}:{checksum} A

Error message

Checksum mismatch for file {}:
Expected: {algo}:{checksum}
Actual:   {algo}:{actual}

What it means

After computing the file's actual digest, ensure_checksum compares it (lowercased) to the expected checksum and throws this error on any mismatch. It is a safety guard against corrupted or tampered downloads.

Source

Thrown at src/hash.rs:134

                let out = cmd!("sha1sum", path).read()?;
                out.split_whitespace().next().unwrap().to_string()
            } else {
                file_hash_prog::<Sha1>(path, pr)?
            }
        }
        "md5" => {
            if use_external_hasher && file::which("md5sum").is_some() {
                let out = cmd!("md5sum", path).read()?;
                out.split_whitespace().next().unwrap().to_string()
            } else {
                file_hash_prog::<Md5>(path, pr)?
            }
        }
        _ => bail!("Unknown checksum algorithm: {}", algo),
    };
    let checksum = checksum.to_lowercase();
    if actual != checksum {
        bail!(
            "Checksum mismatch for file {}:\nExpected: {algo}:{checksum}\nActual:   {algo}:{actual}",
            display_path(path)
        );
    }
    Ok(())
}

pub(crate) fn parse_shasums(text: &str) -> HashMap<String, String> {
    text.lines()
        .filter_map(|l| {
            let mut parts = l.split_whitespace();
            let hash = parts.next()?;
            let name = parts.next()?;
            // Strip coreutils binary-mode marker (e.g. "<hash> *file.tar.gz").
            let name = name.strip_prefix('*').unwrap_or(name);
            Some((name.into(), hash.into()))
        })
        .collect()

View on GitHub (pinned to afd2eddd3a)

Solutions

Delete the downloaded artifact (and mise's cache) and re-download, letting mise recompute the checksum
Verify the expected checksum against the official checksum file from the project's release page for that exact version
If upstream republished/changed the artifact, update the checksum in your config or update mise so the registry has the new value
Check for proxies/VPNs altering content; use a direct connection or different mirror
If the mismatch persists with an official checksum, treat the file as tampered and investigate the source

Example fix

// before
# mise.toml
[tools]
node = { version = "22.3.0", checksum = "sha256:old_stale_hash..." }
// after
# recompute from official release
[tools]
node = { version = "22.3.0", checksum = "sha256:current_official_hash..." }

Defensive patterns

Strategy: retry

Validate before calling

// compare against the official checksum file before installing
let expected: &str = &config_checksum;
assert_eq!(expected.len(), 64, "sha256 checksum should be 64 hex chars");

Try / catch

match ensure_checksum(&path, &algo, &expected) {
    Err(e) if e.to_string().contains("Checksum mismatch") => {
        std::fs::remove_file(&path)?; // drop corrupt artifact
        re_download(&url, &path)?;    // retry once, then compare with official sums
    }
    Err(e) => return Err(e),
    Ok(()) => {},
}

Prevention

Take expected checksums only from official release checksum files
Clear cached downloads after network interruptions
Be suspicious of persistent mismatches: verify TLS/proxy path before overriding

When it happens

Trigger: ensure_checksum called with an expected checksum string that does not equal the actual digest of the file at `path` — corrupted download, truncated partial file, wrong file, or a stale expected checksum after upstream replaced the artifact.

Common situations: Flaky network or proxy corrupted a download; CDN served a newer build than the recorded checksum; manually written checksum in mise.toml taken from the wrong release; MITM tampering attempt.

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Related errors

AI-assisted analysis of jdx/mise@afd2eddd3a (2026-09-09). Data as JSON: /api/errors/ba932ed368d92af6. Report an issue: GitHub.