Go "go.mod requires go >= X (running go Y)" - Fix in CI

The go directive in go.mod is a hard floor. When the toolchain running the build is older than that floor, Go stops before compiling rather than risk using a newer language feature it cannot parse.

What this error means

A build fails with go.mod requires go >= 1.22 (running go 1.20). In CI this means setup-go pinned an older release than the module declares, and a toolchain auto-download was unavailable or disabled.

go: go.mod requires go >= 1.22 (running go 1.20.7)

Common causes

setup-go pinned an older release

The workflow installed a Go version below the floor the go directive declares, so the running binary cannot satisfy go.mod.

go directive bumped without bumping CI

Someone raised the go directive locally but never updated the go-version in the workflow, so CI still runs the old toolchain.

How to fix it

Install a Go that meets the floor

1. Set setup-go to the version (or newer) named by the go directive.
2. Rebuild so the running toolchain satisfies go.mod.

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

Read the directive straight from go.mod

1. Drive the installed version from go.mod so the two never drift.

- uses: actions/setup-go@v5
  with:
    go-version-file: go.mod

How to prevent it

• Use go-version-file: go.mod so CI tracks the directive automatically.
• Bump the workflow go-version whenever you raise the go directive.
• Leave GOTOOLCHAIN=auto so Go can fetch a newer toolchain if needed.

Related guides