jdx/mise · critical

verified checksum file digest does not match existing checks

Error message

verified checksum file digest does not match existing checksum for {filename}

What it means

After mise verifies a download against an aqua checksum file, it records the verified digest in the tool version's lock platform entry. If a checksum already exists in the lockfile for this platform, uses the same algorithm, and differs from the newly verified digest, mise refuses to proceed — the same file now hashes differently, which usually means tampering, a corrupted mirror, or a silently changed upstream release.

Source

Thrown at src/backend/aqua.rs:2744

                && !cosign_already_verified
                && checksum_path.exists()
            {
                self.cosign_checksums(ctx, cosign, pkg, v, tv, &checksum_path)
                    .await?;
            }

            if needs_verified_checksum_binding && checksum_path.exists() {
                let checksum_content = file::read_to_string_bom(&checksum_path)?;
                let checksum_str =
                    self.parse_checksum_from_content(&checksum_content, checksum, filename)?;
                let checksum_val = format!("{}:{}", checksum.algorithm(), checksum_str);
                let platform_key = self.get_platform_key();
                let platform_info = tv.lock_platforms.entry(platform_key).or_default();
                if let Some(existing_checksum) = &platform_info.checksum
                    && same_checksum_algorithm(existing_checksum, &checksum_val)
                    && existing_checksum != &checksum_val
                {
                    bail!(
                        "verified checksum file digest does not match existing checksum for {filename}"
                    );
                }
                platform_info.checksum = Some(checksum_val);
            }
        }
        if let Some(pi) = tv.lock_platforms.get_mut(&platform_key)
            && pi.provenance.is_some()
        {
            pi.github_attestations = None;
        }

        // If lockfile recorded verified provenance, verify that the type matches
        // (checked after all verification methods including cosign have had a chance to record)
        if let Some(expected) = expected_provenance {
            let platform_key = self.get_platform_key();
            let got = tv
                .lock_platforms

View on GitHub (pinned to afd2eddd3a)

Solutions

Treat this as a possible supply-chain issue: verify the upstream release's official checksums before proceeding
Delete the stale lockfile entry (edit mise.lock or remove the platform checksum) only after confirming the new digest is legitimate
Clear the download cache for the tool and re-download from the canonical source
Pin to a different version whose assets were not re-uploaded; report the re-uploaded asset to the upstream project

Example fix

# after confirming upstream intentionally re-published the asset:
mise use -g aqua:owner/repo@1.2.3 --force   # or remove the stale checksum block in mise.lock first

Defensive patterns

Strategy: try-catch

Validate before calling

// before upgrading, compare lockfile checksum vs upstream release notes' published digests
const lock = JSON.parse(fs.readFileSync("mise.lock", "utf8"));
const stored = lock?.["aqua:owner/repo"]?.platforms?.["linux-amd64"]?.checksum;
if (stored) console.log("existing locked checksum:", stored, "— verify against upstream before reinstalling");

Try / catch

try {
  await $`mise install`;
} catch (e) {
  if (String(e).includes("does not match existing checksum")) {
    // DO NOT blindly fix: audit the upstream release for tampering/re-uploads first,
    // then remove the stale checksum entry and reinstall.
    await $`mise use aqua:owner/repo@${version} --force`;
  } else throw e;
}

Prevention

Treat any checksum-change error as a security signal; verify upstream digests before overriding
Never override by editing the lockfile until the new digest is confirmed against the project's official checksums
Watch upstream releases for force-pushed assets; subscribe to release notifications for pinned tools
Use canonical download sources, not third-party mirrors

When it happens

Trigger: Installing or re-verifying an aqua-managed tool (src/backend/aqua.rs:2744) when mise.lock / the lock platform already stores a checksum for the same platform+filename, same algorithm, but the freshly computed digest differs.

Common situations: Upstream force-pushed or re-uploaded a release asset without changing the version tag; a mirror serves a modified artifact; lockfile was generated on a setup where a different (corrupt) artifact was cached; malicious supply-chain 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/5bbf7d05ff051baa. Report an issue: GitHub.