Go GOFLAGS=-mod=readonly conflict - Fix in CI

By Kaveh Alemi·Latchkey

A global GOFLAGS=-mod=readonly forbids editing go.mod for every go command. When a step genuinely needs to update go.mod (a go get, a tidy), readonly blocks it and the command fails.

What this error means

A go get or build under GOFLAGS=-mod=readonly fails with updates to go.mod needed, disabled by -mod=readonly or -mod=mod must be explicitly requested. The flag is right for builds but wrong for steps that must edit go.mod.

go: updates to go.mod needed, disabled by -mod=readonly
	(GOFLAGS=-mod=readonly set in environment)

Common causes

Global readonly applied to mutating steps

GOFLAGS=-mod=readonly is exported job-wide, so even a deliberate go get or tidy is blocked.

go.mod was actually out of date

A readonly build surfaced real drift; the committed go.mod genuinely needs an update.

How to fix it

Tidy locally and commit, keep readonly for builds

1. Run go mod tidy on your machine and commit, so the readonly CI build needs no edits.

go mod tidy
git add go.mod go.sum

Scope -mod=mod to the step that needs it

1. Override the readonly flag only for the command that must edit go.mod.

- run: GOFLAGS=-mod=mod go get github.com/foo/bar@v1.2.0
- run: go build ./...  # inherits -mod=readonly

How to prevent it

• Keep -mod=readonly for builds and commit a tidy go.mod.
• Scope -mod=mod to individual mutating steps, not the whole job.
• Add a git diff --exit-code go.mod go.sum guard so drift fails early.

Frequently asked questions

Related guides

References

• Go documentation
• GitHub Actions documentation