Go "download X: dial tcp: i/o timeout" - Fix in CI

A module download could not establish or finish a connection to the proxy in time. A dial tcp: i/o timeout is a transient network failure that almost always succeeds on retry.

What this error means

A go mod download or build fails with download X: dial tcp 142.250.0.0:443: i/o timeout. Re-running the same job usually works unchanged, the hallmark of a transient issue.

go: github.com/foo/bar@v1.0.0: download github.com/foo/bar:
	dial tcp 142.250.0.0:443: i/o timeout

Common causes

Transient proxy or network hiccup

The path between the runner and proxy.golang.org dropped momentarily, timing out the connection.

No module cache between jobs

Every job re-downloads from the network, multiplying exposure to transient timeouts.

How to fix it

Retry the download

1. Wrap go mod download in a short bounded retry; transient timeouts usually clear immediately.

for i in 1 2 3; do go mod download && break; sleep 5; done

Cache the module cache

1. Cache ~/go/pkg/mod so warm jobs avoid the network entirely.

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

How to prevent it

• Cache ~/go/pkg/mod keyed on go.sum.
• Add a bounded retry around module downloads.
• Consider a closer module mirror for flaky networks.

Related guides