Fix it fast
Most likely: The proxy or origin served bytes that differ from the version previously authenticated by this project or checksum database.
Confirm this is your error
Match the output and confirm you are troubleshooting the same failure.
verifying example.com/mod@v1.2.3: checksum mismatch
downloaded: h1:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
go.sum: h1:BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=
go: example.com/mod@v1.2.3: verifying go.mod: checksum mismatch
SECURITY ERROR
This download does NOT match the one reported by the checksum server.Check the cause
Run focused checks to identify what is failing in this environment.
go version
go env GOPROXY GOSUMDB GOPRIVATE GONOSUMDB GOMODCACHE
go mod download -x <module>@<version>Apply the safe fix
Use the smallest safe change that addresses the confirmed cause.
# Prefer a new immutable release after the divergence is understood
go get <module>@<new-version>Verify it works
Repeat the relevant checks and confirm the original error is gone.
go mod download <module>@<verified-version>
go build ./...Avoid unsafe shortcuts
Keep security and data protections in place while troubleshooting.
- Do not set
GOSUMDB=offas a blanket workaround. - Do not delete
go.sumor the entire module cache before preserving and investigating the evidence.
What This Error Means
Read this as a precise clue about which part of the workflow broke first. Once you know the failing layer, the fix path gets much shorter.
How to Fix It
The fastest fixes here come from checking the immediate failing layer before you change anything unrelated. Make one correction at a time and re-test from the same environment.
Mutated upstream release:publish and consume a new immutable version. Do not rewrite the existing trusted checksum.
Bad proxy object:after confirming upstream bytes, invalidate only the affected proxy entry and investigate the divergence.
Bad local sum:verify upstream content and history, then restore the reviewed checksum file from source control. Never copy the downloaded hash blindly.
Single-runner cache damage:reproduce on a fresh runner, then replace only the affected cache entry.
Possible interception or unexplained divergence:stop the release and escalate through the organization’s supply-chain incident process.
Why It Happens
An upstream author force-moved or rebuilt a tag after consumers had authenticated the original content.
A proxy, mirror, or restored CI cache serves corrupted or inconsistent bytes.
go.sum or go.work.sum contains an incorrect hash from a manual edit or bad merge.
Verify the Fix
Run go mod download <module>@<verified-version> through the intended proxy, and run go build ./... in a fresh environment and review any module-file change.
Preserve evidence and identify the conflicting source
Record go version and go env GOPROXY GOSUMDB GOPRIVATE GONOSUMDB GOMODCACHE before changing anything.
Capture the module, version, host, downloaded hash, and trusted hash from the full error.
Run go mod download -x <module>@<version> from a fresh runner through the intended proxy, then compare the immutable upstream tag before touching any cache.
How Go detects changed module content
Go hashes module zip and go.mod content and compares it with go.sum, go.work.sum, or the configured checksum database. Unlike a missing sum, a mismatch means trusted and downloaded hashes disagree. Treat it as an integrity incident, not network flakiness.
Prevent It From Coming Back
To prevent this, treat version tags and proxy objects as immutable and auditable, monitor cache-integrity failures separately from availability failures, and use the same private-path and checksum policy on laptops, CI, and containers.
Docs and source code
Go module fetch verification source
Current source for checksum mismatch diagnostics and security-error behavior. - Source
A conflicting trusted hash stops the download with a checksum mismatch security error.Go Modules Reference
Official reference for module files, version selection, proxies, private modules, checksums, workspaces, and vendoring. - Source
The go command uses module paths and versions to resolve, download, and authenticate dependencies.Publishing a module
Official guidance that published version tags must remain immutable. - Source
After publishing, do not change a tagged version. Publish a new version instead.