Go "checksum mismatch" / "SECURITY ERROR" in go.sum - Fix in CI

Go downloaded a module and its hash did not match the one recorded in go.sum. Go treats this as a security event because a differing hash can mean the module was tampered with, re-tagged, or served by a mismatched mirror.

What this error means

A go build, go mod download, or go test fails with checksum mismatch and a SECURITY ERROR block listing the recorded hash, the downloaded hash, and the checksum-database value. It is deterministic - the same go.sum fails the same way every run.

go output

verifying github.com/example/lib@v1.4.0: checksum mismatch
	downloaded: h1:abcd1234...
	go.sum:     h1:wxyz9876...

SECURITY ERROR
This download does NOT match an earlier download recorded in go.sum.
The bits may have been replaced on the origin server, or an attacker may
have intercepted the download attempt.

Common causes

The module was re-tagged or republished

An upstream author force-pushed a tag or replaced a release, so the bits behind a version differ from what go.sum recorded. The checksum database and your lockfile now disagree with the live source.

A proxy or mirror served different bytes

A misconfigured GOPROXY, a stale cache, or a corrupted download can deliver content whose hash differs from the recorded one, tripping verification.

go.sum edited or merged incorrectly

A bad merge or a hand-edited go.sum line leaves an incorrect hash that no real download will ever match.

How to fix it

Re-verify against a clean cache

Clear the module cache and re-download so Go fetches fresh bytes and re-checks them against go.sum.

Terminal

go clean -modcache
go mod download
go mod verify

Reset the recorded hash for a legitimately re-tagged module

When you have confirmed the upstream change is intentional and trusted, drop the stale entry and let Go re-record the new hash.

Terminal

# remove the bad lines, then re-resolve
go get github.com/example/lib@v1.4.0
go mod tidy

Pin a known-good version

Identify which module the SECURITY ERROR names.
Move to a fixed release whose bytes are stable (avoid a moving branch pseudo-version).
Commit the updated go.mod and go.sum so CI is reproducible.

How to prevent it

Commit go.sum and treat it as a lockfile; never hand-edit it.
Depend on released tags, not force-pushable branches.
Use a consistent GOPROXY across local and CI so cached bytes agree.

Frequently asked questions

Is a checksum mismatch always an attack?

No - the most common cause is an upstream author re-tagging a release. But Go cannot tell a re-tag from tampering, so it refuses the build either way. Verify the change is intentional before resetting the hash.