Go "go install ...@version requires go >= 1.X" - Fix Tool Installs in CI

Installing a CLI with go install pkg@version builds it against its own go.mod. When that tool requires a newer Go toolchain than the runner has and GOTOOLCHAIN=local blocks auto-upgrade, the install fails before producing a binary.

What this error means

A go install github.com/org/tool@v1.5.0 step fails with tool@v1.5.0 requires go >= 1.23 (running go 1.21; GOTOOLCHAIN=local). Other tools install fine; only the one with a higher go directive fails.

go output

go: github.com/org/tool@v1.5.0 requires go >= 1.23
	(running go 1.21; GOTOOLCHAIN=local)

Common causes

The tool requires a newer toolchain than the runner

The tool’s go.mod sets a go 1.23 directive, but the runner ships an older Go and cannot build it as-is.

GOTOOLCHAIN=local blocks the auto-download

With local, Go will not fetch the newer toolchain needed to build the tool, so it errors instead of upgrading.

How to fix it

Install a new enough Go before the tool

.github/workflows/ci.yml

- uses: actions/setup-go@v5
  with:
    go-version: '1.23'
- run: go install github.com/org/tool@v1.5.0

Allow toolchain auto-management for the install

Let Go download the toolchain the tool requires on demand.

Terminal

GOTOOLCHAIN=auto go install github.com/org/tool@v1.5.0

Pin a tool version your toolchain can build

Check the tool release whose go directive matches your installed Go.
Install that version until you can raise the runner toolchain.
Plan the Go upgrade rather than holding the tool back indefinitely.

How to prevent it

Keep the CI Go version at or above your tools’ requirements.
Leave GOTOOLCHAIN=auto unless you deliberately pin.
Pin tool versions for reproducible installs.