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.

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:
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 mismatchThe 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 fragment | Layer | Fix |
|---|---|---|
checksum mismatch / SECURITY ERROR | go.sum vs content | go clean -modcache, re-download, or remove the stale go.sum line |
missing go.sum entry | go.sum incomplete | go mod download, go mod tidy |
404 Not Found / 410 Gone | Proxy does not have it | GOPROXY=direct, or the correct proxy |
dial tcp … i/o timeout | Network or firewall | Proxy setting, HTTPS_PROXY, or a mirror |
invalid version / unknown revision | Version does not exist | go list -m -versions <module> |
updates to go.mod needed | Graph changed, readonly mode | go mod tidy |
inconsistent vendoring | vendor/ stale | go mod vendor |
reading …: 401 / 403 | Private repo auth | GOPRIVATE + git credentials or insteadOf |
| Variable | Scope | Effect |
|---|---|---|
GOPROXY | Fetching | Comma-separated chain, direct = VCS |
GOSUMDB | Verification | sum.golang.org, off disables |
GOPRIVATE | Both | Paths that skip proxy and sumdb |
GONOSUMDB | Verification | Paths that skip only the database |
GOFLAGS | Behaviour | -mod=mod, -mod=vendor |
GOTOOLCHAIN | Toolchain | Downloads the version go.mod requires |
Practical Edge Cases, Error Fixes & Deep Dive Code Examples
1. A checksum mismatch after a retagged version
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:
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.1If 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
go clean -modcache # nukes $GOMODCACHE; re-downloads everything
go mod download all
go mod verify # reports any module whose content changed on diskgo 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
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
go: github.com/Azure/azure-sdk-for-go@v68.0.0: unrecognized import path
# or a path that exists locally but not in the cacheThe 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
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.
# CI guard
go mod tidy
git diff --exit-code go.mod go.sum6. GOTOOLCHAIN downloads and offline builds
go: downloading go1.24.4 (linux/amd64) ...
go: download go1.24.4 for linux/amd64: toolchain not availableSince 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:
# Dockerfile
FROM golang:1.25-bookworm AS build
ENV GOTOOLCHAIN=local GOFLAGS=-mod=readonlyCommon Compilation/Runtime Mistakes & Version Gotchas
| Mistake | Symptom | Correct approach |
|---|---|---|
Editing go.sum to silence a mismatch | Accepts unverified code | Choose a new version |
GOSUMDB=off as the first fix | Verification disabled repo-wide | GOPRIVATE for the specific path |
GOPRIVATE without git credentials | could not read Username | SSH key or token in CI |
-mod=readonly with a stale go.mod | updates to go.mod needed | go mod tidy, commit |
Committing vendor/ without updating it | inconsistent vendoring | go mod vendor in the same change |
| Hand-built module cache paths | Case-encoding errors | Use go env GOMODCACHE |
GOFLAGS=-mod=vendor in a module with no vendor/ | Build cannot find packages | Drop 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 toolsSmall utilities that fit Go work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Go guides
All Go guidesGo iota: Enumerations, Bitmask Flags, and Constant Expressions
How iota advances per const line, typed enums with gaps, bit flags with 1 << iota, and the unit scale pattern that shifts with one blank line.
Go JSON: Marshaling, Unmarshaling, Struct Tags, and Custom Parsers
Struct tags, omitempty that skips false and zero, custom marshalers without recursion, RawMessage for tagged unions, and float64 precision loss.
Go Strings, Runes, and Bytes: UTF-8 Encoding, Conversion, and Memory
Bytes versus runes, len that counts bytes, slicing that splits characters, Builder for linear concatenation, and normalization the standard library omits.
Go select Statement: Non-Blocking Operations, Timeouts, and Nil Channels
Random choice among ready cases, non-blocking polls with default, nil channels that disable a case, timer reuse, and labeled breaks out of a loop.
More in Go
All Go guidesThe guides filed next to this one in Go, in library order.