Go "updates to go.mod needed" under -mod=readonly - Fix in CI

By Kaveh Alemi·Latchkey

CI builds default to -mod=readonly, which forbids the build from editing go.mod. When the module graph needs a change the committed file does not have, Go refuses rather than silently rewriting it.

What this error means

A go build or go test stops with updates to go.mod needed, disabled by -mod=readonly. The same commands often succeed locally where -mod=mod quietly fixes go.mod, hiding the drift until CI enforces readonly.

go: updates to go.mod needed, disabled by -mod=readonly
	to update it:
	go mod tidy

Common causes

go.mod is missing a required directive

An import added or a dependency bumped needs a require (or an updated go/indirect line) that was never written, so a readonly build cannot proceed without editing the file.

Local builds masked the drift with -mod=mod

Running go build locally without -mod=readonly auto-edits go.mod, so the gap never surfaces until CI runs in readonly mode.

How to fix it

Tidy locally and commit the result

Reconcile go.mod/go.sum with the real import graph, then commit both files so the readonly build has everything it needs.

go mod tidy
git add go.mod go.sum
git commit -m "go mod tidy"

Run readonly locally to reproduce

Match CI by building in readonly mode so drift fails on your machine instead of in the pipeline.

go build -mod=readonly ./...

Guard tidiness in CI

go mod tidy
git diff --exit-code go.mod go.sum

How to prevent it

• Run go mod tidy after every import or dependency change and commit the result.
• Keep CI on -mod=readonly so drift fails fast.
• Add a git diff --exit-code go.mod go.sum guard to the pipeline.

Frequently asked questions

Related guides

References

• Go documentation
• GitHub Actions documentation