Go "go.mod requires go >= 1.X" Toolchain Download Errors in CI

By Daniel Zoghalchali·Latchkey

Resolving the module graph requires a newer Go toolchain than the runner has, and GOTOOLCHAIN=local (or an offline runner) prevents Go from downloading it. The command refuses before building.

What this error means

A go command fails immediately with go.mod requires go >= 1.X (running go 1.Y; GOTOOLCHAIN=local). It happens after a dependency bumped its go directive above your installed toolchain.

go: go.mod requires go >= 1.23 (running go 1.21; GOTOOLCHAIN=local)

Common causes

A dependency raised the required Go version

An upgraded module set a higher go 1.X directive, which propagates into your build’s minimum toolchain requirement.

GOTOOLCHAIN=local blocks auto-download

With local, Go will not fetch a newer toolchain to satisfy the requirement, so it errors instead of upgrading itself.

How to fix it

Install a new enough Go in CI

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

Allow toolchain auto-management

Let Go download the required toolchain on demand.

export GOTOOLCHAIN=auto
go build ./...

Pin a dependency version that fits your toolchain

1. Identify which dependency raised the requirement (go mod graph).
2. If you cannot upgrade Go yet, pin that dependency to a release with a lower go directive.
3. Plan the toolchain upgrade rather than holding back indefinitely.

How to prevent it

• Keep the CI Go version aligned with your dependencies’ requirements.
• Leave GOTOOLCHAIN=auto unless you deliberately pin.
• Upgrade the toolchain proactively when dependencies move.

Frequently asked questions

Related guides

References

• Go documentation
• GitHub Actions documentation