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

By Daniel Zoghalchali·Latchkey

CI builds default to -mod=readonly, which forbids editing go.mod. When the module graph needs a change the committed file lacks, Go refuses instead of rewriting it.

What this error means

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

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

Common causes

go.mod missing a required directive

An added import or a bumped dependency needs a require or updated indirect line that was never written, so a readonly build cannot proceed.

Local builds masked the drift

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

How to fix it

Tidy locally and commit

1. Reconcile go.mod and go.sum with the real import graph using go mod tidy.
2. 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"

Reproduce readonly locally

1. Build with -mod=readonly to match CI behavior on your machine.

go build -mod=readonly ./...

How to prevent it

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

Frequently asked questions

Related guides

References

• Go documentation
• GitHub Actions documentation