go mod "checksum mismatch" in CI: how to fix securely

TL;DR

Checksum mismatch means the downloaded module differs from the recorded hash: a compromised or changed upstream, a proxy serving stale content, or (most commonly) a go.sum updated by a different Go version or a dirty module cache. Never fix it with GONOSUMDB or GOFLAGS=-mod=mod blindly; verify which side changed, then update go.sum deliberately with a trusted toolchain.

The query

go mod "checksum mismatch" in CI: how to fix securely

Use this when

• CI go builds fail with checksum mismatch
• The temptation to disable sum verification appears
• Module proxies might serve stale content
• go.sum was updated by someone else's toolchain

Not for when

• General go mod tidy or version issues
• Private module authentication
• Build (compile) errors

Steps

Step 1: Identify the mismatching module and versions

The error names the module and the two hashes (recorded vs downloaded). Note them; the investigation is about this specific module version, not the whole dependency tree. Expected output: the exact module version under suspicion.

Step 2: Check for toolchain and cache contamination

Verify the CI Go version matches the project's, and clear the module cache for a clean re-download. Mixed toolchains and dirty caches produce mismatches that look like supply-chain attacks but are just local rot. Expected output: contamination ruled out, or the dirty cache found.

Step 3: Check the proxy and GOPROXY settings

If GOPROXY points at a corporate proxy or Athens, verify it serves the same content as the upstream. Stale or rewriting proxies are a real cause; compare the proxy's served zip hash against the public sum database. Expected output: the proxy vindicated or implicated.

Step 4: Update go.sum deliberately, not blindly

If the upstream legitimately re-released (rare) or the old sum was wrong, update go.sum with go mod tidy using the project's pinned Go version, review the diff, and commit it. The diff review is the security control. Expected output: go.sum updated with a reviewed, explainable diff.

Step 5: Pin the toolchain and verify in CI

Pin the Go version (toolchain directive or CI image) so every environment computes the same sums. Add a CI check that go mod verify passes; checksum enforcement is only as strong as its weakest environment. Expected output: reproducible sums across all environments.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstnrVts-tRDiCr453-WWyfA

Resolved from the public thread: https://vectle.com/posts/pstnrVts-tRDiCr453-WWyfA

Thread query: go mod "checksum mismatch" in CI: how to fix securely

TL;DR: Checksum mismatch means the downloaded module differs from the recorded hash: a compromised or changed upstream, a proxy serving stale content, or (most commonly) a go.sum updated by a different Go version or a dirty module cache. Never fix it with GONOSUMDB or GOFLAGS=-mod=mod blindly; verify which side changed, then update go.sum deliberately with a trusted toolchain.