Go — checksum mismatch when downloading a module

Resolve module checksum mismatches by clearing the cache, verifying go.sum, and checking proxies and tags.

intermediatedebugginggomodules

Symptoms

verifying module: checksum mismatch
go.sum differs from the downloaded content
The error appears in CI but not locally
A module version was retracted or its tag moved

Possible causes

The module cache holds corrupted or stale content
go.sum has an entry that does not match the downloaded zip
A proxy serves content that differs from the source
A tag was moved or the module was republished

Diagnosis steps

Clear the module cache

go clean -modcache

Interpretation

Removing cached modules forces a fresh download so stale content cannot mask the true state.

Re-verify against go.sum

go mod verify

Interpretation

This checks downloaded modules against go.sum and reports mismatches, confirming whether the sum or the content is wrong.

Check the proxy

go env GOPROXY GONOSUMCHECK GOSUMDB

Interpretation

A proxy that rewrites or truncates modules causes mismatches; bypassing it with direct mode isolates the cause.

Root cause

The downloaded module content did not hash to the value recorded in go.sum, because of cache corruption, a proxy serving modified content, or a tag that changed after being published.

Fix

Clear the module cache and re-download, correct or regenerate go.sum with go mod tidy when the sum is genuinely outdated, and treat a moved tag as a supply-chain concern to investigate rather than silently accept.

Verify the fix

Run go mod verify and the build and confirm both pass, and confirm the module hash matches across a clean environment.

Symptom walkthrough

Fetching a dependency fails with checksum mismatch while verifying the module against go.sum. Common causes are a corrupted module cache, an outdated sum entry, a proxy that serves altered content, or a published tag that changed. CI may fail while a local cache hides the problem, which makes the environment part of the diagnosis.

Fix in practice

Clear the module cache and re-download, then verify with go mod verify. If the sum is genuinely stale because the version was legitimately republished, tidy the module to update it. When a tag appears to have moved, investigate as a supply-chain risk instead of discarding the check.

Verification

Run go mod verify and a full build and confirm both succeed, ideally in a clean environment with an empty cache. Consistent hashes across environments confirm the fix rather than a local workaround.

Diagnostic commands

Check the behavior with commands like these:

go clean -modcache
go mod verify
go env GOPROXY GONOSUMCHECK GOSUMDB