Go "go: downloading go1.X" Toolchain Fetch Failures in CI

By Daniel Zoghalchali·Latchkey

With GOTOOLCHAIN=auto, Go downloads a newer toolchain on demand when go.mod requires one. That fetch goes over the network and can fail transiently with a timeout or proxy 5xx, even though nothing is wrong with your code.

What this error means

A command prints go: downloading go1.23 (linux/amd64) and then fails with an i/o timeout, connection reset, or 5xx while pulling the toolchain. Re-running the job usually succeeds - the hallmark of a transient network failure.

go: downloading go1.23 (linux/amd64)
go: download go1.23: golang.org/toolchain@v0.0.1-go1.23.linux-amd64:
	reading https://proxy.golang.org/.../@v/....zip: dial tcp: i/o timeout

Common causes

Transient network failure fetching the toolchain

The toolchain zip is downloaded through the module proxy. A brief connectivity blip or an overloaded proxy makes that fetch time out or reset.

A newer toolchain required but not preinstalled

go.mod (or a dependency) requires a Go version newer than the runner ships, so every job triggers an on-demand download that depends on the network.

How to fix it

Preinstall the required toolchain

Install the exact Go version your module needs so no on-demand download is required at build time.

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

Retry the transient download

Because the failure is a network blip, a bounded retry usually clears it.

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

Cache the downloaded toolchain

- 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 your go.mod requires with actions/setup-go.
• Cache the toolchain download so re-fetches are rare.
• Keep the runner Go version aligned with your go/toolchain directives.

Frequently asked questions

Related guides

References

• Go documentation
• GitHub Actions documentation