Go "toolchain not available" (GOTOOLCHAIN) - Fix in CI

By Daniel Zoghalchali·Latchkey

When go.mod requires a newer toolchain than the one installed, Go tries to download it unless GOTOOLCHAIN forbids it. A blocked or failed toolchain download stops the build.

What this error means

A build fails with go: toolchain go1.22.4 not available or a download error, often with GOTOOLCHAIN=local. It means the local Go is too old and the auto-download was disabled or could not reach the network.

go: go.mod requires go >= 1.22.4 (running go 1.21.0; GOTOOLCHAIN=local)
go: toolchain go1.22.4 not available

Diagnose it: module path, proxy, or checksum?

Go module errors name the module but rarely the layer that failed. Separate the three: the module path does not resolve, the proxy cannot serve it, or the checksum database disagrees with what was downloaded.

# what Go resolves and from where
go env GOPROXY GOSUMDB GOPRIVATE GOFLAGS

# does the module resolve at all, bypassing the build?
go list -m -versions github.com/org/module

# verify the module cache against go.sum
go mod verify

# private modules must be excluded from proxy and sumdb
go env -w GOPRIVATE=github.com/yourorg/*

Common causes

GOTOOLCHAIN=local blocks the download

With local set, Go will not fetch a newer toolchain, so an older binary cannot satisfy the directive.

Toolchain download failed transiently

GOTOOLCHAIN=auto tried to download but the network or mirror failed momentarily.

How to fix it

Install a matching toolchain via setup-go

1. Pin setup-go to the version the module requires so no download is needed.

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

Allow the auto-download

1. Leave GOTOOLCHAIN at auto and retry so Go can fetch the required toolchain.

export GOTOOLCHAIN=auto
for i in 1 2 3; do go build ./... && break; sleep 5; done

How to prevent it

• Use go-version-file: go.mod so the installed toolchain matches the directive.
• Leave GOTOOLCHAIN=auto unless you deliberately pin local.
• Cache toolchain downloads to avoid repeated network fetches.

Frequently asked questions

Related guides

References

• Go documentation
• GitHub Actions documentation