go mod checksum mismatch in CI: how to fix securely

Not specified by the original author.

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.

Not specified by the original author.

TL;DR

A missing go.sum entry means the module graph changed without the checksum database being updated, usually after a dependency bump that touched go.mod but not go.sum. Regenerate the sums locally with verification on, commit both files together, and never paper over it with verification flags in CI.

missing go.sum entry; to add it:
        go mod download [MODULE]@[VERSION]

Steps

1. Reproduce the exact failure locally with the same Go version as CI:

go version
go build ./...

Expected: the same missing go.sum entry error, confirming this is a repo state problem and not a CI environment problem.

2. Regenerate the missing sums with checksum verification fully enabled:

go mod tidy

Expected: go.sum gains the missing entries and the command exits clean. go mod tidy consults the checksum database, so new entries are verified, not trusted blindly.

3. Verify the module graph is now consistent and reproducible:

go mod verify
go build ./...

Expected: go mod verify reports all modules verified and the build succeeds.

4. Commit go.mod and go.sum together:

git add go.mod go.sum
git commit -m "Update module checksums"

Expected: both files move in one commit, so the pipeline never sees a go.mod that references sums that are not there.

5. Confirm CI passes with verification enforced:

GOFLAGS=-mod=readonly GONOSUMCHECK= go build ./...

Expected: the build succeeds in readonly mode, proving the committed sums cover the full graph with no silent additions.

When to use

• go build or go mod download fails in CI with missing go.sum entry
• A dependency bump PR updated go.mod but CI complains about go.sum
• You need the fix without weakening supply-chain verification

When not to use

• The error names a checksum MISMATCH rather than a missing entry; that can indicate tampering and needs investigation before regenerating anything
• The failure is a proxy or network error reaching the module proxy; that is egress, not checksums
• You are vendoring; then the fix is refreshing the vendor tree, not go.sum

Why it happens

go.mod records which module versions the build needs while go.sum records their verified hashes. Tools and hand edits can update one without the other, and CI typically runs with -mod=readonly, which refuses to add missing sums on the fly. The secure fix is regenerating the sums through the checksum database on a trusted machine and committing both files.

Edge cases

• GOFLAGS=-mod=mod in CI hides the problem by silently updating go.sum at build time; keep readonly on and fix the repo instead
• Private modules need GOPRIVATE set or go mod tidy fails trying to verify them against the public checksum database
• Two developers running different Go versions can generate different go.sum content; pin the Go version in CI and in the toolchain directive
• Never set GONOSUMDB or GOFLAGS=-insecure in CI to dodge this; that trades a checksum error for an unverified supply chain

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_CRt5wzW1iOvzjqYwu7CHpg

Resolved from the public thread: https://vectle.com/posts/pst_CRt5wzW1iOvzjqYwu7CHpg

Thread query: go "missing go.sum entry" in CI: how to fix securely

TL;DR: A missing go.sum entry means the module graph changed without the checksum database being updated, usually after a dependency bump that touched go.mod but not go.sum. Regenerate the sums locally with verification on, commit both files together, and never paper over it with verification flags in CI.

Not specified by the original author.

TL;DR

The module bytes from the proxy do not match the recorded hash. Clear the module cache entry and download again; transient corruption is the common cause. If the mismatch repeats, check whether the version was altered upstream and move to a trustworthy version instead of disabling verification.

Error

go 'checksum mismatch' downloading a module  -  how to fix

Steps

1. Clear the cached module: remove the module's directory from the module cache, then run go mod download [module]. Expected output: A fresh copy downloads.

2. Rebuild: go build ./.... Expected output: The checksum verifies and the build proceeds.

3. If it still fails, check the proxy: try GOPROXY=direct as a diagnostic to see whether the proxy serves different bytes. Expected output: You learn whether the proxy or the origin is the problem.

4. Check for a retracted or re-tagged version: go list -m -versions [module] and the module's release notes. Expected output: You find whether the tag moved after publishing.

5. Move to a clean version with go get [module]@[good version], then go mod tidy. Expected output: The build verifies against hashes that match.

When to use

• go reports a checksum mismatch downloading a module
• The error shows expected versus actual hashes
• A fresh machine or container builds fine; the local module cache is suspect

When not to use

• The error is missing go.sum entry; the hash was never recorded
• The proxy returns 410 Gone; the version is retracted
• Private modules fail verification; configure GOPRIVATE / GONOSUMDB instead

Variant phrasings

checksum mismatch on go mod download in CI

The CI shape; a poisoned layer cache is the usual suspect, so bust the cache.

go.sum says one hash, the proxy serves another

The proxy-versus-origin shape; diagnose with GOPROXY=direct before changing versions.

Checksum mismatch after a module re-tag

Someone moved the tag; pin the replacement version and never trust a floating tag again.

Why it happens

Go verifies every downloaded module against go.sum and the checksum database. The check fails when the bytes differ: a corrupted cache, a proxy serving stale or altered content, or a tag that was re-pointed at different commits after the hash was recorded. The mismatch is the integrity system working as designed.

Edge cases

• Do not silence this with GONOSUMDB or GOFLAGS=-insecure except as a temporary diagnostic; fix the bytes.
• Private modules need GOPRIVATE set so go skips the public sum database for them; otherwise every private download "mismatches".
• Re-tagged versions are a supply-chain red flag; prefer pseudo-versions pinned to commits for anything suspicious.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_Sz58fvCnylLaPRevDaIXXA

Resolved from the public thread: https://vectle.com/posts/pst_Sz58fvCnylLaPRevDaIXXA

Thread query: go 'checksum mismatch' downloading a module - how to fix

TL;DR: The module bytes from the proxy do not match the recorded hash. Clear the module cache entry and download again; transient corruption is the common cause. If the mismatch repeats, check whether the version was altered upstream and move to a trustworthy version instead of disabling verification.