Go Module Download Timeout - Fix GOPROXY 5xx / i/o timeout in CI

A module download stalled or dropped mid-fetch. The proxy returned a 5xx, the connection reset, or the request timed out - transient network failures that almost always succeed on retry.

What this error means

A go mod download or build fails part way through fetching a module with an i/o timeout, connection reset by peer, or a 5xx from the proxy. Re-running the job usually works unchanged - the hallmark of a transient network issue.

go output

go: github.com/example/lib@v1.4.0: reading
https://proxy.golang.org/github.com/example/lib/@v/v1.4.0.zip:
dial tcp: lookup proxy.golang.org: i/o timeout

Common causes

Transient proxy or network failure

A brief connectivity blip, DNS hiccup, or an overloaded proxy causes the download to time out or reset. Nothing is wrong with your modules.

Large module zips over a slow link

Big module archives on a congested runner network can exceed the default timeouts, especially when the cache is cold.

How to fix it

Cache the module download cache

Caching the module cache between runs means most modules are already local, so a flaky proxy matters far less.

.github/workflows/ci.yml

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

Retry the download with a bounded loop

Because the failure is transient, a short retry usually clears it.

Terminal

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

Use a closer or internal proxy

Point GOPROXY at a geographically closer mirror or an internal pull-through cache (e.g. Athens).
Set GOPROXY=https://proxy.example.com,direct so a private fallback exists.
Pin go.sum so the set of downloads is stable and cacheable.

How to prevent it

Cache ~/go/pkg/mod keyed on go.sum.
Run an internal module proxy for high-volume pipelines.
Pin versions so downloads are deterministic and reusable.