Home › Go

go: go.mod requires go >= 1.xx (running go 1.yy; GOTOOLCHAIN=local) — how to fix

go: go.mod requires go >= 1.23.0 (running go 1.21.6; GOTOOLCHAIN=local)
go: github.com/example/lib@v1.4.0 requires go >= 1.22 (running go 1.21.6; GOTOOLCHAIN=local)

Quick fix: Install a newer Go (or let Go fetch it: go env -w GOTOOLCHAIN=auto), e.g. go install golang.org/dl/go1.23.4@latest && go1.23.4 download. In CI/Docker, bump the image (golang:1.23) or go-version in setup-go. Only lower the go line in go.mod if no dependency needs the newer version.

What it means

Since Go 1.21, the go line in go.mod is a minimum requirement, not a hint:

module example.com/app

go 1.23.0
toolchain go1.23.4

If your installed toolchain is older, Go 1.21+ will by default download the required toolchain automatically (GOTOOLCHAIN=auto). You see this error when that switching is disabled (GOTOOLCHAIN=local) — common in Linux distro packages, some Docker images and corporate setups.

The second form (github.com/example/lib@v1.4.0 requires go >= 1.22) means a dependency needs the newer Go, so lowering your own go line won't help.

Check what you have

go version
go env GOTOOLCHAIN GOROOT
grep -E '^(go|toolchain) ' go.mod

GOTOOLCHAIN may be set in the environment, in go env -w config ($(go env GOENV)), or by the distro in $GOROOT/go.env.

Fix 1: let Go download the toolchain

go env -w GOTOOLCHAIN=auto
go version        # run inside the module; downloads the needed version

The toolchain is fetched as a module (golang.org/toolchain) through your GOPROXY. If you're behind a proxy that blocks it, use Fix 2.

Fix 2: install a newer Go

Official tarball (Linux amd64 example):

curl -LO https://go.dev/dl/go1.23.4.linux-amd64.tar.gz
sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go1.23.4.linux-amd64.tar.gz
export PATH=/usr/local/go/bin:$PATH

Or install a side-by-side version with the existing toolchain:

go install golang.org/dl/go1.23.4@latest
go1.23.4 download
go1.23.4 build ./...

macOS: brew upgrade go. Ubuntu's golang-go package is often behind — use the tarball, snap install go --classic, or the longsleep/golang-backports PPA.

Fix 3: CI and Docker

FROM golang:1.23 AS build      # match or exceed go.mod

GitHub Actions — read the version from go.mod so they never drift:

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

Fix 4: the dependency upgrade was unintended

If go get -u raised the go line (Go bumps it when a dependency requires it), you can pin the dependency to an older version that supports your Go:

go get github.com/example/lib@v1.3.2
go mod tidy

Then check the result with go mod graph | grep example/lib. Only lower the go directive by hand (go mod edit -go=1.21) if nothing in the module graph needs more — go mod tidy will tell you if it does.

Go 1.20 and older don't understand three-part versions like go 1.21.0 or the toolchain line, and fail with this message or unknown directive: toolchain. The only real fix is to upgrade to Go 1.21+; editing go.mod to go 1.21 just moves the problem to the dependencies.

Last updated 2026-11-10.