Go "go.mod requires go >= 1.xx" - Fix in CI

The go directive in go.mod sets a minimum toolchain version. If CI runs an older Go, the build refuses rather than risk using unsupported features.

What this error means

A build fails with go.mod requires go >= 1.22 (running go 1.21; GOTOOLCHAIN=local). It means setup-go pinned an older version than the module declares, or GOTOOLCHAIN=local blocked an auto-upgrade.

go: go.mod requires go >= 1.22.0 (running go 1.21.6; GOTOOLCHAIN=local)

Common causes

CI Go version below the directive

setup-go installed an older Go than the module go directive requires.

GOTOOLCHAIN=local blocks the upgrade

With GOTOOLCHAIN=local Go will not download a newer toolchain, so an older binary cannot satisfy the directive.

How to fix it

Install a matching Go version

1. Set setup-go to the version the module requires (or newer).

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

Allow the toolchain auto-download

1. Leave GOTOOLCHAIN at auto so Go can fetch the required toolchain when the local one is too old.

export GOTOOLCHAIN=auto
go build ./...

How to prevent it

• Pin the CI Go version to match the go.mod directive.
• Bump setup-go when you raise the go directive.
• Leave GOTOOLCHAIN=auto unless you deliberately pin a toolchain.

Related guides