Go "checksum mismatch" (GONOSUMDB) - Fix in CI

By Daniel Zoghalchali·Latchkey

go.sum records a cryptographic hash for every module version. A mismatch means the bytes Go fetched differ from what go.sum recorded - a re-tagged version, a tampered mirror, or a stale go.sum entry.

What this error means

A build fails with verifying module: checksum mismatch between go.sum and the downloaded zip. The fetched content does not match the recorded hash.

verifying example.com/lib@v1.2.0: checksum mismatch
	downloaded: h1:abc...
	go.sum:     h1:xyz...
SECURITY ERROR

Common causes

Upstream version re-tagged

A mutable tag was moved so the content no longer matches the recorded checksum.

Stale or corrupted go.sum entry

A bad merge or partial download left go.sum disagreeing with the real module.

How to fix it

Re-verify a trusted version

1. Clear the module cache, re-download, and confirm the checksum is consistent.
2. If the version was re-tagged, pin a fixed immutable version.

go clean -modcache
go mod download
go mod verify

Scope GONOSUMDB to private hosts only

1. Limit checksum-DB bypass to private prefixes; never disable verification for public modules.

env:
  GONOSUMDB: git.acme.com/*

How to prevent it

• Pin immutable versions; avoid mutable tags.
• Keep go.sum committed and verified in CI.
• Scope checksum-DB bypass narrowly to private hosts.

Frequently asked questions

Related guides

References

• Go documentation
• GitHub Actions documentation