missing go.sum entry and inconsistent vendoring: Go Module Fixes
Readonly module mode will not repair your files. go mod tidy fixes the checksums, go mod vendor fixes the tree, and neither belongs in CI as a workaround.

Introduction & Quick Summary
Symptom. A build that worked on a laptop fails in CI with missing go.sum entry for module providing package github.com/stretchr/testify/assert (imported by example.com/app); to add: go mod download github.com/stretchr/testify, or a container build fails with go: inconsistent vendoring in /src: github.com/spf13/cobra@v1.9.1: is explicitly required in go.mod, but not marked as explicit in vendor/modules.txt.
Cause. Since Go 1.16 the build commands run in -mod=readonly mode: go build and go test will not edit go.mod or go.sum behind your back, and they verify that both files are complete for the packages being compiled. A missing go.sum entry means the hash for that module version was never recorded; inconsistent vendoring means vendor/ no longer matches go.mod, usually because a dependency was added or bumped without re-running go mod vendor.
Fix. go mod tidy writes the missing requirements and checksums from source; go mod vendor rebuilds vendor/ from go.mod. Commit both go.mod and go.sum (and vendor/ if you vendor), and make CI run go mod verify so a corrupted module cache fails loudly instead of producing a subtly different binary.
Core Mechanics, Signatures & Reproducible Setup
The module graph has three artefacts and each error names one of them:
go.mod— the requirements: module path,godirective,require,replace,exclude.go.sum— the transparency record: ah1:hash per module and pergo.modfile, for every version the build touches.vendor/— a copy of the source withvendor/modules.txtdescribing what is inside.
A reproducer for the go.sum error, without any private infrastructure:
mkdir gosum-demo && cd gosum-demo
go mod init example.com/app
cat > main.go <<'EOF'
package main
import (
"fmt"
"github.com/google/uuid"
)
func main() { fmt.Println(uuid.New().String()) }
EOF
GOFLAGS=-mod=readonly go build ./...
# missing go.sum entry for module providing package github.com/google/uuidgo mod tidy # adds the require line and both hashes
go mod verify # 'all modules verified'
go build ./...A reproducer for inconsistent vendoring, which is a different repair:
go mod init example.com/v && printf 'package main\nfunc main(){}\n' > main.go
go mod vendor # creates vendor/modules.txt
go get github.com/spf13/cobra@v1.9.1 # changes go.mod only
go build ./...
# go: inconsistent vendoring in /…: github.com/spf13/cobra@v1.9.1:
# is explicitly required in go.mod, but not marked as explicit in vendor/modules.txt
go mod vendor # re-syncs vendor/ with go.modThe build-mode flags decide whether these are errors or automatic fixes:
| Flag | Behaviour | Use in |
|---|---|---|
-mod=readonly | Default since 1.16; error if files need changes | CI, production builds |
-mod=mod | Updates go.mod/go.sum as needed | Local development |
-mod=vendor | Uses vendor/, ignores the module cache | Container builds |
GOFLAGS=-mod=mod | Global default override | Legacy projects only |
Key Comparison Table
The five module errors look alike and have different causes:
| Error | Meaning | Fix |
|---|---|---|
missing go.sum entry | Checksum never recorded for a needed version | go mod tidy or go mod download <mod> |
inconsistent vendoring | vendor/ out of sync with go.mod | go mod vendor |
SECURITY ERROR / checksum mismatch | Downloaded content differs from the recorded hash | go clean -modcache, then re-download |
module … found, but does not contain package | Version exists, package path is wrong | Fix the import path or the version |
requires go >= 1.XX | Dependency needs a newer toolchain | Raise the go/toolchain line, install that Go |
404 Not Found from proxy | Private module or wrong path case | GOPRIVATE, GONOSUMDB, check case |
Which command to run depends on what is out of date:
| Situation | go mod tidy | go mod vendor | go mod download |
|---|---|---|---|
| New import in code | Yes | If vendoring | No |
go.sum incomplete in CI | Yes | No | Yes, if go.mod is correct |
| Dependency bumped manually | Yes | Yes | No |
vendor/ missing entirely | No | Yes | No |
| Offline build from cache | No | No | Yes |
Practical Edge Cases, Error Fixes & Deep Dive Code Examples
1. go.sum is intentionally not committed
Some .gitignore templates still exclude go.sum. That does not break local builds — the file is created on demand — but it breaks every -mod=readonly build in CI, and it silently allows two machines to resolve different content. Commit it; the file is small and changes only when dependencies change:
git check-ignore -v go.sum # empty output means it is tracked
git add go.sum && git commit -m "chore: track go.sum"2. Vendor directory present, module mode expected
Go switches to -mod=vendor automatically when vendor/modules.txt exists and the go directive is 1.14 or later. A repository that half-migrated to vendoring therefore stops consulting the module cache, and a replace to a local directory works differently:
go env GOFLAGS
go build -mod=mod ./... # bypass vendor/ for one command
rm -rf vendor && go mod tidy # abandon vendoring deliberatelyDo not keep both workflows: either vendor and run go mod vendor in the pre-commit hook, or do not vendor and let CI use the module proxy cache.
3. Docker builds that copy go.mod before main.go
A common Dockerfile layer copies go.mod and go.sum, runs go mod download, then copies the source. If go.sum is stale relative to go.mod, the download layer fails with missing go.sum entry even though go mod tidy works locally:
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -trimpath -o /out/app ./cmd/appRun go mod tidy && go mod verify in the same commit that changes dependencies, otherwise the layer cache hides the drift until a clean build.
4. Checksum mismatch after a force-pushed tag
SECURITY ERROR with checksum mismatch means the proxy served bytes that do not match the recorded hash. This happens when a maintainer re-tags a release or a replace points at a moved branch:
go clean -modcache
GONOSUMDB= GOSUMDB=sum.golang.org go mod download all
go mod verifyNever "fix" this by deleting the go.sum line for that module: the hash is the only protection against a compromised proxy, and deleting it changes what your binary contains.
5. Private modules and the proxy
A private repository returns 404 Not Found through proxy.golang.org, and go get reports a module that plainly exists. GOPRIVATE marks a path prefix as private so the proxy and the checksum database are skipped:
go env -w GOPRIVATE='github.com/myorg/*'
go env -w GONOSUMDB='github.com/myorg/*'
GIT_TERMINAL_PROMPT=0 go mod download # proves credentials, not the proxy, are the issueIn CI, the credential is usually an SSH key or a GITHUB_TOKEN in .netrc; the error text differs (404 versus terminal prompts disabled), which tells you whether the network path or the authentication is wrong.
6. Toolchain directives after a Go upgrade
A dependency that requires Go 1.24 fails on a machine with Go 1.23 and a toolchain line that pins the older version. Go 1.21+ downloads a newer toolchain automatically unless GOTOOLCHAIN=local:
go env GOTOOLCHAIN GOROOT GOVERSION
go get go@1.24 toolchain@go1.24Pinning toolchain in go.mod is a reproducibility feature, not a hack: it makes every developer and CI runner agree on the compiler that produced the checksums.
Common Compilation/Runtime Mistakes & Version Gotchas
- Running
go getinside avendor/project. It updatesgo.modand leavesvendor/inconsistent;go mod vendorafterwards, or-mod=modfor the duration of the change. GOFLAGS=-mod=modin CI as a workaround. It hides drift and lets the build modify tracked files. Fix the files instead, and keep-mod=readonlyso the failure is visible.- Editing
go.sumby hand. Adding a line without a hash, or copying a hash from another project, fails verification in a way that looks like a corrupted cache. go mod tidyremoving a dependency. Test files and build-tagged files count as imports; a dependency used only under a build tag needs the tag present in the environment (GOOS,GOARCH, or-tags) or it will be pruned.- Case-sensitivity in module paths.
github.com/MyOrg/libandgithub.com/myorg/libare different modules; the proxy serves only the lower-cased form and a mismatch yields a confusing 404. - Docker build cache and private modules.
RUN --mount=type=cache,target=/go/pkg/modpersists credentials-adjacent downloads; make sureGOPRIVATEis set in the image environment, not only in your shell. - Go 1.16 behaviour change in old guides. Instructions that say "the build will update
go.modautomatically" describe Go 1.15 and earlier; on any modern version the build refuses and asks for-mod=mod.
Related tools. When a dependency bump changes generated code, diff the old and new files with the text diff tool to separate real API changes from formatting noise, and if the module embeds a JSON schema, check it with the JSON formatter before regenerating mocks.
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 http.Client: unexpected EOF and Connection Reuse Leaks
A body closed without being read cannot be reused, and descriptors pile up. Idle timeouts shorter than the upstream's, MaxIdleConnsPerHost and safe retries.
Go context.DeadlineExceeded vs Canceled and Goroutine Leaks
A deadline is retryable and a cancellation is not, and both arrive wrapped. The errors.Is checks, the four handler timeouts, and the goroutine dump that names the leak.
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.
Go 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.
More in Go
All Go guidesThe guides filed next to this one in Go, in library order.