jdx/mise · error

verified checksum file digest does not match expected checks

Error message

verified checksum file digest does not match expected checksum for {artifact_filename}

What it means

verify_checksum_file_matches_expected verifies that the artifact's checksum file digest matches the checksum recorded at lock time. When an expected checksum exists, uses the same algorithm, and the computed `algo:hex` value differs, it bails — meaning the downloaded artifact or its checksum file does not match what was locked/verified previously (possible corruption or tampering).

Source

Thrown at src/backend/aqua.rs:1993

    fn verify_checksum_file_matches_expected(
        &self,
        checksum_config: &AquaChecksum,
        checksum_path: &Path,
        artifact_filename: &str,
        expected_checksum: Option<&str>,
    ) -> Result<()> {
        let checksum_content = file::read_to_string_bom(checksum_path)?;
        let checksum_str = self.parse_checksum_from_content(
            &checksum_content,
            checksum_config,
            artifact_filename,
        )?;
        let checksum_val = format!("{}:{}", checksum_config.algorithm(), checksum_str);
        if let Some(expected) = expected_checksum
            && same_checksum_algorithm(expected, &checksum_val)
            && expected != checksum_val
        {
            bail!(
                "verified checksum file digest does not match expected checksum for {artifact_filename}"
            );
        }
        Ok(())
    }

    pub(crate) fn from_arg(ba: BackendArg) -> Self {
        let full = ba.full_without_opts();
        let mut id = full.split_once(":").unwrap_or(("", &full)).1;
        if !id.contains("/") {
            id = REGISTRY
                .get(id)
                .and_then(|t| t.backends.iter().find_map(|s| s.full.strip_prefix("aqua:")))
                .unwrap_or_else(|| {
                    warn!("invalid aqua tool: {}", id);
                    id
                });
        }

View on GitHub (pinned to afd2eddd3a)

Solutions

1. Delete the cached/downloaded artifact and retry the install to rule out a corrupted download.
2. If the release was legitimately re-published, refresh the locked checksum (re-run the install/lock resolution and commit the updated mise.lock).
3. Verify the lockfile's expected checksum corresponds to the same platform's artifact, not another platform's.
4. If mismatch persists unexpectedly, treat it as a potential supply-chain issue and compare against upstream-signed provenance before proceeding.

Example fix

# before
mise.lock: checksum = "sha256:abc123..." (stale, release re-tagged)
mise install --locked  # verified checksum file digest does not match expected checksum for example_1.0_Linux_x86_64.tar.gz
# after
rm -rf ~/.local/share/mise/downloads/aqua:owner/repo/1.0
mise install && git add mise.lock && git commit -m "chore: refresh mise.lock checksums"

# shell: clear a possibly-corrupt cached download before reinstalling
rm -rf "$(mise where aqua:owner/repo 2>/dev/null || true)" ~/.local/share/mise/downloads/aqua:owner/repo/*
mise install

retry_install_with_cache_clear(|| mise install, attempts: 2)
// on repeated checksum-mismatch, stop and treat as a supply-chain signal:
// compare against upstream-signed release provenance before trusting artifacts.

When it happens

Trigger: verify_provenance_at_lock_time computes a digest for artifact_filename and compares it to the expected `algorithm:hash` string; any mismatch in the same-algorithm comparison raises the error. Also exercised by test_verify_checksum_file_reads_utf16.

Common situations: Upstream released new artifacts under the same version tag (release was re-tagged); CDN/proxy served a corrupted or different file; lockfile checksum copied from a different platform's artifact; MITM/tampering caught by provenance verification.

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

• brew-cask:{}: cask metadata has no sha256
• no checksum entry found for {filename} in checksum file
• verified checksum file digest does not match existing checks
• Checksum mismatch for file {}: Expected: {algo}:{checksum} A
• {target} on '{}' changed after it was installed; another wri

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