Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Go Module Errors: Checksum Mismatch, 404s, and Proxy Failures

A checksum mismatch is not a cache bug. Separate the proxy, the sum database, and go.sum, then fix the layer the message names instead of editing the hash.

~5 min readGo
#Go#Modules#CI#Dependencies
3D illustration of a module cube verified against a checksum seal beside a proxy pipe

Introduction & Quick Summary

Symptom. Any of: go: github.com/x/y@v1.2.3: verifying module: checksum mismatch with an SECURITY ERROR block and a go.sum entry that does not match; dial tcp 142.250.x.x:443: i/o timeout on go mod tidy; module github.com/x/y: reading https://proxy.golang.org/...: 404 Not Found; go: updates to go.mod needed, disabled by -mod=readonly; or inconsistent vendoring: github.com/x/y@v1.2.3 is explicitly required in go.mod, but not marked as explicit in vendor/modules.txt.

Cause. Module fetching has three independent trust layers: the VCS (or proxy) that serves the code, the checksum database that vouches for it, and go.sum that records what you accepted. A failure in any one produces an error that looks like the others. The common real causes are a GOPROXY that does not reach a private repository, a tag that was moved after being fetched (the hash changed, go.sum did not), a corporate proxy that blocks proxy.golang.org, a vendor/ directory out of sync with go.mod, and a module path with uppercase letters that encodes differently in the cache.

Fix. Identify the layer from the message: verifying module / checksum mismatch is the sum database or go.sum; 404 or 410 is the proxy path; i/o timeout / connection refused is the network; updates to go.mod needed is the module graph; inconsistent vendoring is the vendor directory. Each has a separate remedy, below.

Core Mechanics, Signatures & Reproducible Setup

GOPROXY defaults to https://proxy.golang.org,direct (with GOSUMDB=sum.golang.org). The go command asks the proxy for <module>/@v/<version>.info and .zip, verifies the hash against go.sum, and consults the checksum database the first time it sees a version. GOPRIVATE/GONOSUMDB/GONOSUMCHECK (the modern spelling is GONOSUMDB → GONOSUMDB is legacy; the current pair is GONOSUMDB/GOPRIVATE) mark module paths that should skip both the proxy and the sum database.

Reproduce the failure classes against a throwaway module:

bash
mkdir -p /tmp/moddemo && cd /tmp/moddemo go mod init example.com/moddemo # 1. unreachable proxy GOPROXY=https://127.0.0.1:1 go get github.com/google/uuid@v1.6.0 # go: ... dial tcp 127.0.0.1:1: connect: connection refused # 2. wrong version go get github.com/google/uuid@v9.9.9 # invalid version: unknown revision v9.9.9 # 3. checksum mismatch (edit go.sum by hand) go get github.com/google/uuid@v1.6.0 sed -i 's/^github.com\/google\/uuid v1.6.0 h1:.*/github.com\/google\/uuid v1.6.0 h1:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=/' go.sum go build ./... # verifying module: checksum mismatch

The SECURITY ERROR block is deliberate: it means the module content does not match what go.sum (or the database) recorded, and the go command refuses to use it.

Key Comparison Table

Error fragmentLayerFix
checksum mismatch / SECURITY ERRORgo.sum vs contentgo clean -modcache, re-download, or remove the stale go.sum line
missing go.sum entrygo.sum incompletego mod download, go mod tidy
404 Not Found / 410 GoneProxy does not have itGOPROXY=direct, or the correct proxy
dial tcp … i/o timeoutNetwork or firewallProxy setting, HTTPS_PROXY, or a mirror
invalid version / unknown revisionVersion does not existgo list -m -versions <module>
updates to go.mod neededGraph changed, readonly modego mod tidy
inconsistent vendoringvendor/ stalego mod vendor
reading …: 401 / 403Private repo authGOPRIVATE + git credentials or insteadOf
VariableScopeEffect
GOPROXYFetchingComma-separated chain, direct = VCS
GOSUMDBVerificationsum.golang.org, off disables
GOPRIVATEBothPaths that skip proxy and sumdb
GONOSUMDBVerificationPaths that skip only the database
GOFLAGSBehaviour-mod=mod, -mod=vendor
GOTOOLCHAINToolchainDownloads the version go.mod requires

Practical Edge Cases, Error Fixes & Deep Dive Code Examples

1. A checksum mismatch after a retagged version

code
verifying github.com/acme/lib@v0.9.1: checksum mismatch downloaded: h1:newHash… go.sum: h1:oldHash… SECURITY ERROR This download does NOT match an earlier download recorded in go.sum.

The repository's tag was moved, or the proxy cached a different artifact than the one go.sum recorded. Confirm which side is right before changing anything:

bash
go mod download -json github.com/acme/lib@v0.9.1 | jq '.Sum, .GoModSum' # compare with the published hash on the proxy's web page curl -s https://sum.golang.org/lookup/github.com/acme/lib@v0.9.1

If the upstream tag really moved, the correct action is to pick a new version rather than to edit go.sum — editing the file accepts content nobody vouched for. Removing the stale pair (go mod edit -droprequire then re-add) is only right when you introduced the mismatch, for example by copying a go.sum between projects.

2. Clearing a poisoned module cache

bash
go clean -modcache # nukes $GOMODCACHE; re-downloads everything go mod download all go mod verify # reports any module whose content changed on disk

go mod verify checks the extracted module directories against go.sum without network access, which distinguishes "the cache is corrupt" from "the download is different". In CI, go clean -modcache is often cheaper than debugging a shared cache keyed too loosely — a cache shared between branches with different go.sum files produces mismatches that look random.

3. Private modules: GOPRIVATE plus git auth

bash
export GOPRIVATE=github.com/acme/*,git.internal.example.com/* export GONOSUMDB=$GOPRIVATE export GOFLAGS=-mod=mod # SSH instead of HTTPS for the private host git config --global url."git@github.com:acme/".insteadOf "https://github.com/acme/"

GOPRIVATE makes the go command bypass the proxy and the checksum database for those paths, which is required — a private module cannot be verified by a public database. The fetch then goes through git, so the CI user needs an SSH key or a token in a credential helper. The failure when it is missing is fatal: could not read Username for 'https://github.com', surfaced as a go mod download error that names the module.

4. Case encoding in the module cache

code
go: github.com/Azure/azure-sdk-for-go@v68.0.0: unrecognized import path # or a path that exists locally but not in the cache

The module cache encodes uppercase letters as ! plus lowercase: github.com/Azure becomes github.com/!azure. A script that constructs cache paths by hand, or a global file-system cache restored from a case-insensitive volume, breaks on this. The fix is never to hand-build cache paths; go env GOMODCACHE and the go command's own layout are the contract. On macOS, a case-insensitive checkout of a module whose path differs only by case also fails verification — unpack to a case-sensitive directory.

5. vendor/ that disagrees with go.mod

bash
go mod vendor # regenerate from go.mod/go.sum go mod verify go build -mod=vendor ./...

inconsistent vendoring means vendor/modules.txt no longer matches the requirements. Committing vendor/ is a legitimate choice for reproducible builds, but then every dependency change must include the regenerated directory — a CI check that runs go mod tidy && git diff --exit-code catches the omission before a broken build does.

bash
# CI guard go mod tidy git diff --exit-code go.mod go.sum

6. GOTOOLCHAIN downloads and offline builds

code
go: downloading go1.24.4 (linux/amd64) ... go: download go1.24.4 for linux/amd64: toolchain not available

Since Go 1.21 a go directive newer than the installed toolchain makes the go command download the requested toolchain. In an air-gapped build this fails. Set GOTOOLCHAIN=local to refuse the download with a clear error, and pin the image's Go version instead:

yaml
# Dockerfile FROM golang:1.25-bookworm AS build ENV GOTOOLCHAIN=local GOFLAGS=-mod=readonly

Common Compilation/Runtime Mistakes & Version Gotchas

MistakeSymptomCorrect approach
Editing go.sum to silence a mismatchAccepts unverified codeChoose a new version
GOSUMDB=off as the first fixVerification disabled repo-wideGOPRIVATE for the specific path
GOPRIVATE without git credentialscould not read UsernameSSH key or token in CI
-mod=readonly with a stale go.modupdates to go.mod neededgo mod tidy, commit
Committing vendor/ without updating itinconsistent vendoringgo mod vendor in the same change
Hand-built module cache pathsCase-encoding errorsUse go env GOMODCACHE
GOFLAGS=-mod=vendor in a module with no vendor/Build cannot find packagesDrop the flag or vendor

Version notes: GOFLAGS=-mod=mod overrides the default readonly behaviour introduced in Go 1.16, which is why old scripts that "fixed" a build with it now hide a missing go mod tidy. Go 1.21 began enforcing the go directive as a minimum toolchain and added GOTOOLCHAIN; a module that declares go 1.24 on a 1.22 image downloads a toolchain rather than failing, so a build that worked online breaks in a network-restricted runner. Go 1.17 introduced module graph pruning and changed what go.sum records, which is why an old go.sum can look stable and still be incomplete for a newer toolchain. Go 1.24's tool directives in go.mod add another reason for the module graph to change when a tool's version moves.

For the surrounding work, the hash tool reproduces a h1: checksum from a zip when you need to compare a proxy's claim with a local artifact, the base64 tool decodes a private module's basic-auth token stored in a CI secret before you test it by hand, and the text diff tool compares two go.sum files after a bump that changed more lines than expected. A single go mod tidy in a branch, diffed against main, is the fastest way to see which dependency pulled in a new transitive module.

Try matching browser tools

All tools

Small utilities that fit Go work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Go guides

More in Go

All Go guides

The guides filed next to this one in Go, in library order.