Go "note: module requires Go 1.X" - Fix Version Mismatch in CI

By Daniel Zoghalchali·Latchkey

The Go toolchain on the runner is older than what your module or one of its dependencies requires. Go surfaces an otherwise-cryptic compile error and appends note: module requires Go 1.X to explain the real cause.

What this error means

A build fails with a confusing syntax or compile error, followed by note: module ... requires go >= 1.X (running go 1.Y). The same code builds on a newer toolchain. It is deterministic and tied to the installed Go version.

./main.go:10:6: undefined: min
note: module requires Go 1.21

# or
go: go.mod requires go >= 1.22 (running go 1.20; GOTOOLCHAIN=local)

Common causes

The runner Go is older than the go directive

Your go.mod go 1.22 line (or a dependency’s) requires a newer toolchain than the runner has installed, so newer language features or APIs fail to compile.

GOTOOLCHAIN=local pins to the old toolchain

With GOTOOLCHAIN=local, Go will not auto-download a newer toolchain, so it errors instead of upgrading itself to satisfy the requirement.

How to fix it

Install the required Go version in CI

- uses: actions/setup-go@v5
  with:
    go-version: '1.22'
- run: go version

Let Go manage the toolchain

With toolchain management on, Go downloads the version your go.mod requires automatically.

export GOTOOLCHAIN=auto
go build ./...

Align the go directive with what you support

1. Check the go 1.X line in go.mod against your installed toolchain.
2. Either raise the runner’s Go version or lower the directive if the features allow.
3. Build a matrix of Go versions if you support several.

How to prevent it

• Pin the Go version in CI with actions/setup-go to match your go.mod.
• Keep the go directive aligned with the toolchain you run.
• Leave GOTOOLCHAIN=auto unless you deliberately want a fixed version.

Frequently asked questions

Related guides

References

• Go documentation
• GitHub Actions documentation