Go "verifying X: checksum mismatch" against GOSUMDB - Fix in CI
By Kaveh Alemi·Latchkey
Go verifies every download against go.sum and the public sum database (GOSUMDB). A mismatch means the bytes you got do not match a recorded checksum - a security signal, not noise.
What this error means
A download fails with verifying X: checksum mismatch and SECURITY ERROR, showing the downloaded hash versus the recorded one. It can mean a republished module, a stale go.sum, or a tampering proxy.
go
verifying github.com/foo/bar@v1.2.3: checksum mismatch
downloaded: h1:aaa...
sum.golang.org: h1:bbb...
SECURITY ERROR
This download does NOT match the one reported by the checksum server.
Diagnose it: module path, proxy, or checksum?
Go module errors name the module but rarely the layer that failed. Separate the three: the module path does not resolve, the proxy cannot serve it, or the checksum database disagrees with what was downloaded.
Terminal
# what Go resolves and from where
go env GOPROXY GOSUMDB GOPRIVATE GOFLAGS
# does the module resolve at all, bypassing the build?
go list -m -versions github.com/org/module
# verify the module cache against go.sum
go mod verify
# private modules must be excluded from proxy and sumdb
go env -w GOPRIVATE=github.com/yourorg/*
Common causes
Module republished under the same version
A tag was force-moved or re-released with different content, so the recorded hash no longer matches.
Stale or hand-edited go.sum
go.sum carries an old or altered checksum that no longer matches the real bytes.
Proxy serving different content
A misbehaving or poisoned proxy returned bytes that disagree with GOSUMDB.
How to fix it
Investigate before trusting
Treat the mismatch as a security signal, not a flake.
Confirm the upstream version was not force-pushed; if it was, pin a clean version.
Refresh go.sum for a legitimate change
Remove the stale entry and re-download to record the current checksum after verifying the source.
Terminal
GOFLAGS=-mod=mod go mod download github.com/foo/bar
go mod tidy
How to prevent it
Pin exact versions and avoid mutable tags.
Never disable the sum database as a blanket fix.
Cache the module cache so all jobs verify against the same bytes.
Frequently asked questions
What causes Go "verifying X: checksum mismatch" against GOSUMDB?
There are 3 common causes: module republished under the same version, stale or hand-edited go.sum, and proxy serving different content. A tag was force-moved or re-released with different content, so the recorded hash no longer matches.
How do I fix Go "verifying X: checksum mismatch" against GOSUMDB?
There are 2 fixes depending on which cause you have: investigate before trusting and refresh go.sum for a legitimate change. Work through them in order, since the first is the most common.
What does Go "verifying X: checksum mismatch" against GOSUMDB actually mean?
A download fails with verifying X: checksum mismatch and SECURITY ERROR, showing the downloaded hash versus the recorded one.
How do I stop Go "verifying X: checksum mismatch" against GOSUMDB happening again?
Pin exact versions and avoid mutable tags. The prevention section lists 3 changes that keep it from recurring.
