Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

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.

~5 min readGo
#Go#Modules#Build#CI
3D illustration of module crates in a vendor shelf with one crate missing as a dashed outline

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, go directive, require, replace, exclude.
  • go.sum — the transparency record: a h1: hash per module and per go.mod file, for every version the build touches.
  • vendor/ — a copy of the source with vendor/modules.txt describing what is inside.

A reproducer for the go.sum error, without any private infrastructure:

bash
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/uuid
bash
go 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:

bash
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.mod

The build-mode flags decide whether these are errors or automatic fixes:

FlagBehaviourUse in
-mod=readonlyDefault since 1.16; error if files need changesCI, production builds
-mod=modUpdates go.mod/go.sum as neededLocal development
-mod=vendorUses vendor/, ignores the module cacheContainer builds
GOFLAGS=-mod=modGlobal default overrideLegacy projects only

Key Comparison Table

The five module errors look alike and have different causes:

ErrorMeaningFix
missing go.sum entryChecksum never recorded for a needed versiongo mod tidy or go mod download <mod>
inconsistent vendoringvendor/ out of sync with go.modgo mod vendor
SECURITY ERROR / checksum mismatchDownloaded content differs from the recorded hashgo clean -modcache, then re-download
module … found, but does not contain packageVersion exists, package path is wrongFix the import path or the version
requires go >= 1.XXDependency needs a newer toolchainRaise the go/toolchain line, install that Go
404 Not Found from proxyPrivate module or wrong path caseGOPRIVATE, GONOSUMDB, check case

Which command to run depends on what is out of date:

Situationgo mod tidygo mod vendorgo mod download
New import in codeYesIf vendoringNo
go.sum incomplete in CIYesNoYes, if go.mod is correct
Dependency bumped manuallyYesYesNo
vendor/ missing entirelyNoYesNo
Offline build from cacheNoNoYes

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:

bash
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:

bash
go env GOFLAGS go build -mod=mod ./... # bypass vendor/ for one command rm -rf vendor && go mod tidy # abandon vendoring deliberately

Do 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:

dockerfile
COPY go.mod go.sum ./ RUN go mod download COPY . . RUN CGO_ENABLED=0 go build -trimpath -o /out/app ./cmd/app

Run 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:

bash
go clean -modcache GONOSUMDB= GOSUMDB=sum.golang.org go mod download all go mod verify

Never "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:

bash
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 issue

In 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:

bash
go env GOTOOLCHAIN GOROOT GOVERSION go get go@1.24 toolchain@go1.24

Pinning 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 get inside a vendor/ project. It updates go.mod and leaves vendor/ inconsistent; go mod vendor afterwards, or -mod=mod for the duration of the change.
  • GOFLAGS=-mod=mod in CI as a workaround. It hides drift and lets the build modify tracked files. Fix the files instead, and keep -mod=readonly so the failure is visible.
  • Editing go.sum by 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 tidy removing 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/lib and github.com/myorg/lib are 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/mod persists credentials-adjacent downloads; make sure GOPRIVATE is 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.mod automatically" 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 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.