Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Go: updates to go.mod needed; to update it: go mod tidy

Go builds read-only and will not edit go.mod. Run go mod tidy, understand the -mod modes, and keep vendor and go.sum in step.

~5 min readGo
#Go#Modules#Build#CI
A go module file plate with a missing require slot, amber readonly lock and cyan tidy tool

Introduction & Quick Summary

text
go: updates to go.mod needed; to update it: go mod tidy

Go built with -mod=readonly and found that the module graph in go.mod does not match what the code imports. Since Go 1.16 that is the default for go build, go test, and go vet, so a missing require line is a hard error instead of a silent edit.

The four situations behind it:

  • An import was added and go.mod was not updated. The usual case after merging a branch or pulling someone else's commit.
  • go.sum is complete but go.mod is missing a requirement, for example after go get in another module or a manual edit.
  • GOFLAGS=-mod=readonly or -mod=vendor is set in CI, so a build that used to auto-update now fails.
  • Vendoring drifted. vendor/modules.txt disagrees with go.mod, and the message is the same one until go mod vendor runs.
MessageMeaningFix
updates to go.mod neededMissing or stale requirementgo mod tidy
missing go.sum entry for moduleChecksum file incompletego mod tidy or go mod download
inconsistent vendoringvendor/ differs from go.modgo mod vendor
no required module provides packageImport cannot be resolved at allgo get the module
go.mod file indicates go 1.24, but maximum supported version is 1.22Toolchain too oldUpgrade Go or lower the directive

Core Mechanics, Signatures & Reproducible Setup

-mod=readonly makes the go command promise not to modify go.mod or go.sum. If a build needs a change, it reports what it would have done and exits non-zero. -mod=mod performs the update in place. -mod=vendor reads vendor/ and fails if it is inconsistent with the module graph. The default since Go 1.16 is readonly when go.mod is tidy, and it became vendor automatically when a vendor/ directory exists and the go directive is 1.14 or newer.

A reproduction is one import with no requirement:

bash
mkdir -p /tmp/modfix && cd /tmp/modfix go mod init example.com/app cat > main.go <<'EOF' package main import ( "fmt" "golang.org/x/text/language" ) func main() { fmt.Println(language.English) } EOF go build ./...
text
main.go:7:2: no required module provides package golang.org/x/text/language; to add it: go get golang.org/x/text/language

After the package is added once, a second edit to go.mod by hand produces the other message:

bash
go get golang.org/x/text@v0.31.0 go build ./... # ok # remove the require line by hand, keep go.sum go build ./... # go: updates to go.mod needed; to update it: go mod tidy

Key Comparison Table

The three modes decide whether a build is allowed to edit the module files, and CI usually needs a different mode from a developer machine.

-mod valueReadsMay edit go.modTypical use
readonlygo.mod and go.sumNoDefault since 1.16, CI
modgo.modYesLocal work, go get replacement
vendorvendor/NoReproducible builds with vendoring
auto (GOFLAGS unset)go.mod, or vendor/ if presentFollows the mode chosenDefault behaviour

The commands that fix the state differ in what they rewrite, so running the wrong one leaves the error or rewrites more than intended.

CommandUpdates go.modUpdates go.sumRemoves unused requirementsTouches vendor/
go mod tidyYesYesYesNo
go get pkg@versionYes, adds or bumpsYesNoNo
go mod downloadNoYesNoNo
go mod vendorNoNoNoYes
go mod verifyNoNoNoNo, checks only

Practical Edge Cases, Error Fixes & Deep Dive Code Examples

Tidy, then commit both files

go mod tidy adds missing requirements, removes unused ones, and prunes the graph for the go directive in use. The diff is the review artifact, so commit go.mod and go.sum together.

bash
go mod tidy -v git diff --stat go.mod go.sum go build ./... && go test ./...
bash
# see what tidy would change without writing, in a clean tree cp go.mod /tmp/go.mod.bak && cp go.sum /tmp/go.sum.bak go mod tidy -diff

-diff is available in Go 1.23 and later. On older toolchains, copy the files first and compare with diff, and check that no // indirect requirement disappeared while still being needed.

When a build must not be blocked

During a migration or a large merge, -mod=mod lets the build proceed and updates the files as a side effect. That is acceptable locally and wrong in CI, because the build output depends on an unreviewed change.

bash
GOFLAGS=-mod=mod go build ./... go mod tidy && git diff go.mod
bash
# CI: fail fast, never mutate GOFLAGS=-mod=readonly go build ./...

Setting GOFLAGS in the environment overrides the default for every command in the job, which is why a runner can behave differently from a laptop.

Vendoring and vendor/modules.txt

A repository with vendor/ builds from that directory. Adding an import without re-vendoring produces inconsistent vendoring or the same updates to go.mod needed message, depending on which file is stale.

bash
go mod tidy go mod vendor git status --short vendor/ | head go build -mod=vendor ./...
bash
# confirm the build is really using vendor/ go list -m all >/dev/null && go env GOFLAGS && ls vendor/modules.txt

If vendor/modules.txt lists a module version that go.mod no longer has, the build fails before compiling anything.

The go directive and toolchain lines

A go.mod written by a newer toolchain can declare a version the local go does not understand, which is a different failure with a similar shape. The toolchain line makes Go download a matching toolchain automatically in 1.21 and later.

text
module example.com/app go 1.24.0 toolchain go1.24.3 require golang.org/x/text v0.31.0
bash
go version go env GOTOOLCHAIN GOTOOLCHAIN=auto go build ./...

GOTOOLCHAIN=local refuses the download and reports the version mismatch instead, which is the correct setting for an air-gapped CI.

Private modules and GOPRIVATE

A missing requirement is sometimes a private module that go mod tidy cannot fetch, and the error names a proxy or a 404 rather than the import.

bash
go env GOPRIVATE GOPROXY GONOSUMDB go env -w GOPRIVATE=github.com/company/* go env -w GONOSUMDB=github.com/company/*
bash
# confirm access before tidying git ls-remote https://github.com/company/lib.git | head -3 GOPROXY=direct go get github.com/company/lib@latest

GOPROXY=direct bypasses the module proxy for one command, which separates a proxy problem from a credentials problem.

Workspaces with go.work

A go.work file changes which module versions are used without editing each go.mod. A build inside the workspace can succeed while a build of a single module fails, because the workspace supplies a replacement.

bash
go work init ./service ./lib go work use ./other go work sync
bash
# build as a consumer would, ignoring the workspace GOWORK=off go build ./...

GOWORK=off is the fastest way to reproduce a CI failure that only happens outside the developer's workspace.

Common Compilation/Runtime Mistakes & Version Gotchas

Running go build and hoping it edits the files. It has not since Go 1.16. go mod tidy or -mod=mod is the explicit step.

Committing only go.sum. A checksum entry without the matching requirement fails on the next clean build, because go.sum is verified against go.mod, not the other way round.

Tidying with a different Go version than production. go mod tidy run by a newer toolchain can drop requirements the older compiler needs, and it rewrites the go directive. Run it with the version CI uses.

Ignoring // indirect markers. Removing an indirect requirement that a dependency still needs produces a build failure in a package you did not touch. Let tidy decide.

Editing go.mod by hand during a merge. Requirements and go.sum hashes drift, and the next build fails with a checksum mismatch rather than a missing module.

Version notes. -mod=readonly became the default in Go 1.16. Go 1.17 changed the graph to require all transitive modules explicitly, so a go.mod from 1.16 gains many // indirect lines after the first tidy. Go 1.21 added the toolchain line and automatic toolchain selection. go mod tidy -diff and go get -tool are newer additions, and go mod verify has been available since modules were introduced.

Order: go mod tidy, then git diff to review what changed, then go build ./... and go test ./... with -mod=readonly so the next missing requirement is caught before CI. When the change is a version bump, the text diff on go.mod and go.sum shows which module moved, and the env reader confirms the GOFLAGS and GOPROXY a runner actually uses.

Official references: Go modules reference and go mod tidy.

Official references

primary documentation

The Go documentation that defines the behaviour this guide explains.

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.