go 'checksum mismatch' downloading a module - how to fix

TL;DR

The module bytes from the proxy do not match the recorded hash. Clear the module cache entry and download again; transient corruption is the common cause. If the mismatch repeats, check whether the version was altered upstream and move to a trustworthy version instead of disabling verification.

Error

go 'checksum mismatch' downloading a module  -  how to fix

Steps

1. Clear the cached module: remove the module's directory from the module cache, then run go mod download [module]. Expected output: A fresh copy downloads.

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

3. If it still fails, check the proxy: try GOPROXY=direct as a diagnostic to see whether the proxy serves different bytes. Expected output: You learn whether the proxy or the origin is the problem.

4. Check for a retracted or re-tagged version: go list -m -versions [module] and the module's release notes. Expected output: You find whether the tag moved after publishing.

5. Move to a clean version with go get [module]@[good version], then go mod tidy. Expected output: The build verifies against hashes that match.

When to use

• go reports a checksum mismatch downloading a module
• The error shows expected versus actual hashes
• A fresh machine or container builds fine; the local module cache is suspect

When not to use

• The error is missing go.sum entry; the hash was never recorded
• The proxy returns 410 Gone; the version is retracted
• Private modules fail verification; configure GOPRIVATE / GONOSUMDB instead

Variant phrasings

checksum mismatch on go mod download in CI

The CI shape; a poisoned layer cache is the usual suspect, so bust the cache.

go.sum says one hash, the proxy serves another

The proxy-versus-origin shape; diagnose with GOPROXY=direct before changing versions.

Checksum mismatch after a module re-tag

Someone moved the tag; pin the replacement version and never trust a floating tag again.

Why it happens

Go verifies every downloaded module against go.sum and the checksum database. The check fails when the bytes differ: a corrupted cache, a proxy serving stale or altered content, or a tag that was re-pointed at different commits after the hash was recorded. The mismatch is the integrity system working as designed.

Edge cases

• Do not silence this with GONOSUMDB or GOFLAGS=-insecure except as a temporary diagnostic; fix the bytes.
• Private modules need GOPRIVATE set so go skips the public sum database for them; otherwise every private download "mismatches".
• Re-tagged versions are a supply-chain red flag; prefer pseudo-versions pinned to commits for anything suspicious.

Provenance

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

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

Thread query: go 'checksum mismatch' downloading a module - how to fix

TL;DR: The module bytes from the proxy do not match the recorded hash. Clear the module cache entry and download again; transient corruption is the common cause. If the mismatch repeats, check whether the version was altered upstream and move to a trustworthy version instead of disabling verification.