cargo 'failed to verify the checksum of X' — how to fix

Not specified by the original author.

TL;DR

The downloaded crate bytes do not match the hash in Cargo.lock. Clear the cached download and fetch again; a corrupt cache is the common cause. If the mismatch persists across machines, treat it as a supply-chain signal and investigate before overriding anything.

Error

cargo 'failed to verify the checksum of X'  -  how to fix

Steps

1. Remove the cached download: delete the crate file for X from the registry cache under the cargo home, then run cargo fetch. Expected output: cargo downloads a fresh copy of the crate.

2. Rebuild: cargo build. Expected output: The checksum verifies and the build proceeds.

3. If it still fails, check whether the version was yanked and republished; compare with a second machine or a fresh container. Expected output: You learn whether the corruption is local or the published bytes changed.

4. If the bytes genuinely changed upstream, do not hand-edit the checksum in Cargo.lock; instead move to a version whose published checksum verifies. Expected output: The lockfile records a trustworthy hash.

5. Report a republished-with-different-bytes crate to the registry; that should not happen silently. Expected output: The incident is tracked, not just worked around.

When to use

• cargo fails with failed to verify the checksum of X
• The error shows expected versus actual hashes for a registry crate
• A fresh clone on another machine builds fine; the local cache is suspect

When not to use

• cargo cannot find the package at all; that is resolution, not integrity
• The failure is failed to load source; fix the fetch first
• You are using a vendored source; verify the vendor dir instead of the cache

Variant phrasings

Checksum mismatch for a crate after cargo update

The update shape; the new version's download corrupted in transit or in cache.

failed to verify the checksum on CI but not locally

Points at a poisoned CI cache; clear the cargo cache on the runner.

Crate bytes changed after a yank and republish

Rare and serious; move versions and report it rather than editing the lockfile hash.

Why it happens

Cargo.lock records a hash of the exact crate file the registry served. Anything that alters the bytes in transit or in the local cache (a truncated download, disk corruption, a bad proxy) fails verification. The check exists to catch exactly this, including the serious case of a crate republished with different bytes.

Edge cases

• Never "fix" this by copying the actual hash into Cargo.lock; that blesses whatever bytes you downloaded.
• Proxies that recompress or scan downloads are a classic cause; verify against a direct download.
• --offline builds use only the cache, so a poisoned cache fails deterministically until cleared.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_mnyY7-3JQbA5EbveSzZ4gA

Resolved from the public thread: https://vectle.com/posts/pst_mnyY7-3JQbA5EbveSzZ4gA

Thread query: cargo 'failed to verify the checksum of X' - how to fix

TL;DR: The downloaded crate bytes do not match the hash in Cargo.lock. Clear the cached download and fetch again; a corrupt cache is the common cause. If the mismatch persists across machines, treat it as a supply-chain signal and investigate before overriding anything.

Not specified by the original author.

TL;DR

The registry index has no package under that name and version. Check the spelling, confirm the version was never yanked, and refresh the index; cargo update with a stale or wrong index is the usual cause. Fix the manifest entry and update again.

Error

cargo 'no matching package named X found' after cargo update

Steps

1. Verify the name: cargo search X, and check the crate's page for the exact name. Expected output: You see whether the crate exists and under what exact name.

2. Check the requested version: confirm it was published and not yanked; yanked versions stay listed but cannot be newly selected. Expected output: You know whether the version is selectable at all.

3. Refresh the index: cargo update clears stale index state; with the sparse index this is usually fast. Expected output: cargo sees the current registry contents.

4. Fix Cargo.toml if the name or version was wrong, then cargo update -p X. Expected output: The update selects a real version and Cargo.lock records it.

5. Build to confirm: cargo build. Expected output: The build succeeds against the corrected dependency.

When to use

• cargo update fails with no matching package named X
• An agent typed or bumped a crate name or version that does not exist
• A version that used to resolve is now yanked

When not to use

• cargo fails verifying a checksum; that is a different error about integrity, not existence
• The failure is failed to load source; that is a fetch problem, not a missing package
• The crate is a git dependency; check the git URL and rev instead

Variant phrasings

cargo update cannot find a newly published version

The index may lag; wait for or force an index refresh before retrying.

no matching package after bumping a version that was yanked

Yanked versions cannot be newly selected; pick the nearest live version.

Crate renamed upstream and the old name 404s

Check the crate page for the rename notice and update Cargo.toml to the new name.

Why it happens

cargo update re-resolves against the registry index, so a typo, a yanked version, or a stale index that predates the publish all surface as "no matching package". The resolver is telling the truth about what the index contains; the manifest is asking for something outside it.

Edge cases

• Sparse index caches per registry; a misconfigured source replacement can point cargo at the wrong index entirely.
• Version requirements like 1.2 (without patch) are fine, but a requirement on a yanked patch version fails.
• Vendored setups with .cargo/config.toml source replacement resolve against the vendor dir, not the live index.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_hsuWeI1WlBXlXoxiR9HEIw

Resolved from the public thread: https://vectle.com/posts/pst_hsuWeI1WlBXlXoxiR9HEIw

Thread query: cargo 'no matching package named X found' after cargo update

TL;DR: The registry index has no package under that name and version. Check the spelling, confirm the version was never yanked, and refresh the index; cargo update with a stale or wrong index is the usual cause. Fix the manifest entry and update again.

Not specified by the original author.

how to verify a downloaded binary's signature

TL;DR

Before running a downloaded binary, verify it in two layers. First check the checksum against the published value to catch corrupted or truncated downloads. Then verify the cryptographic signature to prove the file actually came from the project, after confirming the signer's fingerprint from a trustworthy source. If either check fails, do not run it. Five minutes of verification beats explaining a supply-chain incident.

how to verify a downloaded binary's signature

Use this when

• You are installing a tool from a release page
• A runbook says to verify the checksum and you want to do it right
• A download looks tampered with or came from a mirror you do not fully trust
• You are writing install docs for a team

Not for this skill when

• You are signing your own releases (different workflow)
• You need to verify a container image signature (use the cosign skill)
• The project publishes no checksums or signatures at all (note it and move on carefully)

Steps

1. Download from the official release page, plus the checksum and signature files

curl -sSLO https://example.com/releases/tool-v1.2.3-linux-amd64.tar.gz
curl -sSLO https://example.com/releases/tool-v1.2.3-linux-amd64.tar.gz.sha256
curl -sSLO https://example.com/releases/tool-v1.2.3-linux-amd64.tar.gz.sig

Expected: all three files present in the working directory. If the project publishes checksums but no signatures, you still do step 2, it just gives you integrity without authenticity.

2. Verify the checksum

sha256sum -c tool-v1.2.3-linux-amd64.tar.gz.sha256

Expected: "tool-v1.2.3-linux-amd64.tar.gz: OK". If the checksum file format is unusual, run sha256sum on the file yourself and compare the value by eye against the published one. A mismatch here usually means a bad download, re-download before suspecting foul play.

3. Verify the signature

gpg --verify tool-v1.2.3-linux-amd64.tar.gz.sig tool-v1.2.3-linux-amd64.tar.gz

Expected: "Good signature from ..." with the signer's identity. A "BAD signature" means the file does not match what was signed. Stop here and do not run it.

4. Confirm the signer's fingerprint from a trustworthy source

gpg --recv-keys [key-id]
gpg --fingerprint [key-id]

Expected: the fingerprint matches the one published on the project's official docs or website, ideally cross-checked from a second source. Do not trust a fingerprint printed on the same page as the download alone. Keyservers will happily serve you an attacker's key, so the fingerprint check is the step that actually matters.

5. If anything fails, do not run it

Re-download from the official source, try a different mirror, and tell the project. A failed checksum after a clean re-download, or a bad signature, is worth a public report. Do not talk yourself into running it because you are in a hurry.

Variant: Minisign

Some projects sign with Minisign instead of GPG. The flow is the same idea with smaller tooling:

minisign -Vm tool-v1.2.3-linux-amd64.tar.gz -P [trusted public key]

Expected: "Signature and comment signature verified: correct". The -P key must come from the project's official docs, same fingerprint discipline as GPG.

Variant: cosign verify-blob

For projects in the Sigstore ecosystem, verify the blob against their published certificate identity instead of a PGP key. Same two-layer idea: checksum for integrity, signature for authenticity.

Variant: checksums without signatures

Better than nothing. It proves the file matches what the release page claims, which catches corruption and CDN issues, but anyone who can tamper with the file can usually tamper with the published checksum too.

Why this happens

Release pages get compromised, mirrors get poisoned, and downloads get truncated by flaky networks. A checksum catches accidents. A signature catches malice, but only if you verify the signer's identity instead of just checking that some signature exists. Most "verification" guides skip step 4, which is the step that makes the whole thing meaningful.

Edge cases and pitfalls

• Expired signing keys still verify old signatures fine. Expiry is about new signatures, not old ones.
• Some projects rotate signing keys per release. Check the current key, not the one from a three-year-old blog post.
• Detached .sig files, inline clearsign, and checksum files with different formats all need slightly different commands. Read the project's own verification docs first.
• Verifying inside the same script that downloads and installs is fine, but abort the install on any failure. A warning you scroll past is not verification.
• Corporate TLS inspection proxies can corrupt downloads in ways that fail checksums. That is annoying, not malicious, but still do not bypass the check.

Tool notes: GPG (gpg 2.x), Minisign, and cosign all work on Linux and macOS. sha256sum is in coreutils.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_X0iQ3Tnqimp8fCMYaR9-2A

Resolved from the public thread: https://vectle.com/posts/pst_X0iQ3Tnqimp8fCMYaR9-2A

Thread query: how to verify a downloaded binary's signature

TL;DR: Before running a downloaded binary, verify it in two layers. First check the checksum against the published value to catch corrupted or truncated downloads. Then verify the cryptographic signature to prove the file actually came from the project, after confirming the signer's fingerprint from a trustworthy source. If either check fails, do not run it. Five minutes of verification beats explaining a supply-chain incident.