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.

Introduction & Quick Summary
go: updates to go.mod needed; to update it: go mod tidyGo 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.modwas not updated. The usual case after merging a branch or pulling someone else's commit. go.sumis complete butgo.modis missing a requirement, for example aftergo getin another module or a manual edit.GOFLAGS=-mod=readonlyor-mod=vendoris set in CI, so a build that used to auto-update now fails.- Vendoring drifted.
vendor/modules.txtdisagrees withgo.mod, and the message is the same one untilgo mod vendorruns.
| Message | Meaning | Fix |
|---|---|---|
updates to go.mod needed | Missing or stale requirement | go mod tidy |
missing go.sum entry for module | Checksum file incomplete | go mod tidy or go mod download |
inconsistent vendoring | vendor/ differs from go.mod | go mod vendor |
no required module provides package | Import cannot be resolved at all | go get the module |
go.mod file indicates go 1.24, but maximum supported version is 1.22 | Toolchain too old | Upgrade 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:
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 ./...main.go:7:2: no required module provides package golang.org/x/text/language;
to add it:
go get golang.org/x/text/languageAfter the package is added once, a second edit to go.mod by hand produces the other message:
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 tidyKey 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 value | Reads | May edit go.mod | Typical use |
|---|---|---|---|
readonly | go.mod and go.sum | No | Default since 1.16, CI |
mod | go.mod | Yes | Local work, go get replacement |
vendor | vendor/ | No | Reproducible builds with vendoring |
auto (GOFLAGS unset) | go.mod, or vendor/ if present | Follows the mode chosen | Default 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.
| Command | Updates go.mod | Updates go.sum | Removes unused requirements | Touches vendor/ |
|---|---|---|---|---|
go mod tidy | Yes | Yes | Yes | No |
go get pkg@version | Yes, adds or bumps | Yes | No | No |
go mod download | No | Yes | No | No |
go mod vendor | No | No | No | Yes |
go mod verify | No | No | No | No, 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.
go mod tidy -v
git diff --stat go.mod go.sum
go build ./... && go test ./...# 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.
GOFLAGS=-mod=mod go build ./...
go mod tidy && git diff go.mod# 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.
go mod tidy
go mod vendor
git status --short vendor/ | head
go build -mod=vendor ./...# confirm the build is really using vendor/
go list -m all >/dev/null && go env GOFLAGS && ls vendor/modules.txtIf 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.
module example.com/app
go 1.24.0
toolchain go1.24.3
require golang.org/x/text v0.31.0go 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.
go env GOPRIVATE GOPROXY GONOSUMDB
go env -w GOPRIVATE=github.com/company/*
go env -w GONOSUMDB=github.com/company/*# confirm access before tidying
git ls-remote https://github.com/company/lib.git | head -3
GOPROXY=direct go get github.com/company/lib@latestGOPROXY=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.
go work init ./service ./lib
go work use ./other
go work sync# 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 documentationThe Go documentation that defines the behaviour this guide explains.
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: cannot find main module and where go.mod is looked up
The go command searched upward and found no module. Create it at the right level, join modules with go.work, and check GOMOD before guessing.
Go: build constraints exclude all Go files in a package
The package vanished for this platform, not the code. Read the ignored file list, then rename a suffix or pass the tag.
Go: cgo: C compiler "gcc" not found in a minimal image
Why a project with no C fails on a C compiler, how to prove which package pulls cgo, and what changes when a library really needs it.
Go 1.26: go fix rewrites, errors.AsType and go.mod surprises
go fix now modernizes code, errors.AsType compiles instead of panicking, and go mod init writes the previous minor on purpose.
More in Go
All Go guidesThe guides filed next to this one in Go, in library order.