Go GOTOOLCHAIN "toolchain not available" - Fix Auto Downloads in CI

By Kaveh Alemi·Latchkey

With GOTOOLCHAIN=auto, Go downloads a required newer toolchain through the module proxy. When the proxy is off, the runner is air-gapped, or GOTOOLCHAIN is pinned to local, the on-demand download cannot happen and Go errors that the toolchain is not available.

What this error means

A command fails with go: toolchain go1.23 not available or cannot download toolchain: GOPROXY=off. It is either a transient fetch failure (clears on retry) or a configuration that blocks the download entirely (no retry will help).

go output

go: toolchain go1.23 required by go.mod, but GOTOOLCHAIN=local
# or, with the proxy disabled:
go: download toolchain: GOPROXY list is not the empty string but contains no entries

Common causes

GOTOOLCHAIN=local or GOPROXY=off blocks the download

A pinned local toolchain or a disabled proxy means Go cannot fetch the newer toolchain go.mod requires, so it fails deterministically.

Transient failure fetching the toolchain

When auto is allowed, the toolchain still comes over the network; a brief proxy or DNS blip can make that fetch fail and then succeed on retry.

How to fix it

Preinstall the required toolchain

On air-gapped or proxy-off runners, install the exact Go version so no download is needed.

.github/workflows/ci.yml

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

Allow the auto-download and retry transient failures

Terminal

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

Cache the downloaded toolchain

.github/workflows/ci.yml

- uses: actions/cache@v4
  with:
    path: ~/go/pkg/mod/golang.org/toolchain
    key: go-toolchain-${{ hashFiles('go.mod') }}

How to prevent it

Preinstall the toolchain on air-gapped or proxy-off runners.
Leave GOTOOLCHAIN=auto and a reachable GOPROXY for on-demand fetches.
Cache the toolchain download so re-fetches are rare.

Frequently asked questions

What causes "toolchain not available"?

A pinned local toolchain or a disabled proxy means Go cannot fetch the newer toolchain go.mod requires, so it fails deterministically.

How do I fix toolchain not available?