Go "updates to go.mod needed, disabled by -mod=mod" - Fix in CI

CI builds default to a mode that forbids rewriting go.mod. When the module graph needs a change the committed file lacks, Go refuses instead of editing it silently.

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 Go quietly edits go.mod, hiding the drift until 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 bumped dependency needs a require or indirect line that was never written.

Local builds masked the drift

Local go commands auto-edit go.mod, so the gap never surfaced until readonly CI ran.

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

Reproduce readonly locally

1. Build with -mod=readonly to match CI behavior before pushing.

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.

Related guides