The command go get hangs, times out, or returns dial tcp: i/o timeout — a familiar situation for developers behind a corporate firewall, in a closed network, or when working with private GitLab/GitHub repositories. In 90% of cases, the reason lies in incorrect configuration of GOPROXY, absence of GOPRIVATE, or blocking direct access to proxy.golang.org by a firewall. Let’s discuss how to fix this properly.
Why Go modules are not downloading
Since Go 1.13, the module system by default accesses the public proxy proxy.golang.org and the checksum server sum.golang.org. If both services are blocked at the network level (this is typical for Russia, China, and corporate segments with restrictions), the command go build or go mod tidy will hang until timeout, and then return an error:
go: github.com/some/[email protected]: reading github.com/some/package/@v/v1.2.3.info: dial tcp 142.250.x.x:443: i/o timeout
There are three typical scenarios that cause module downloads to fail:
- Network blocking — the provider or corporate firewall cuts off access to the Google infrastructure that hosts proxy.golang.org and sum.golang.org.
- Private repositories — the module is located in an internal GitLab/Bitbucket, and the public GOPROXY cannot physically reach it, while also trying to verify its checksum on sum.golang.org, which it should not.
- Proxy server in the network without configured environment variables — traffic goes out only through HTTP/SOCKS5 proxies, but Go does not know about it because
go getuses the standard net/http client, which reads environment variables, not system proxy settings from the browser.
Next, we will discuss each case with specific commands and configuration files.
What is GOPROXY and how does it work
GOPROXY is an environment variable that tells the Go tooling where to download modules from. By default (starting with Go 1.14), its value is:
GOPROXY=https://proxy.golang.org,direct
The comma-separated value is a list of sources that Go iterates through in order. direct means "download directly from VCS (git, svn, hg) if the proxy returns 404 or 410." If the proxy is physically unavailable (timeout, not 404), Go does not move to the next source — it simply hangs or fails on timeout. This is a key point that many do not understand: the fallback mechanism only works for "module not found," not for "network unavailable."
In addition to proxy.golang.org, there are public mirrors that can be used as alternatives:
| GOPROXY server | URL | Feature |
|---|---|---|
| Google official | proxy.golang.org | Often blocked in closed networks |
| goproxy.cn | goproxy.cn | Mirror from the Chinese community, consistently available |
| Astra (goproxy.io) | goproxy.io | Alternative global mirror |
| Athens (self-hosted) | your server | Full control, suitable for corporate module caching |
Configuring GOPROXY: working configurations
Go environment variables can be set temporarily (for the session) or permanently using go env -w, which saves the values in the Go configuration file (usually ~/.config/go/env on Linux/macOS and %APPDATA%\go\env on Windows).
Permanent configuration (recommended):
go env -w GOPROXY=https://goproxy.cn,direct go env -w GOSUMDB=sum.golang.org
Check the current value:
go env GOPROXY
If you need multiple mirrors with fallback:
go env -w GOPROXY=https://goproxy.cn,https://goproxy.io,https://proxy.golang.org,direct
An important nuance: if the first proxy in the list responds with a timeout instead of an HTTP error, moving to the next source can take up to a minute for each module — this kills build speed in CI. Therefore, if the network physically cannot reach the first proxy, it is better to remove it from the list immediately or configure network access through a proxy server (see the section below), rather than relying on fallback.
If you want to completely disable access to external proxies and work only from the local cache or directly from VCS:
go env -w GOPROXY=direct
GOPRIVATE, GONOSUMCHECK, and GOSUMDB
When a module is located in an internal Git repository (corporate GitLab, Bitbucket Server, self-hosted Gitea), Go will still by default attempt to check it through the public GOPROXY and verify the hash via GOSUMDB — which is impossible because private code is not published externally. The result is an error 410 Gone or verifying module: checksum mismatch.
The solution is the GOPRIVATE variable, which tells Go: "these module paths are private, do not go to the public proxy for them and do not verify the checksum."
go env -w GOPRIVATE=gitlab.company.com/*,github.com/myorg/*
GOPRIVATE automatically sets two flags at once: GONOSUMCHECK (disables checksum verification via GOSUMDB) and GOPROXY=direct for the specified paths. But if more fine-tuned configuration is needed, they can be set separately:
go env -w GONOSUMCHECK=1 go env -w GOSUMDB=off go env -w GONOSUMDB=gitlab.company.com/*
For private repositories on GitHub, you also need to configure git to use a token instead of SSH when cloning via HTTPS, because the Go tooling uses git under the hood:
git config --global url."https://${GITHUB_TOKEN}@github.com/".insteadOf "https://github.com/"
This command replaces all HTTPS requests to github.com with requests that include the token in the URL, allowing the Go client to download private modules without interactive login/password input.
HTTP/HTTPS proxies for go get
If the office or server is behind a corporate HTTP proxy (e.g., Squid), Go will not automatically know about it — it only reads the environment variables HTTP_PROXY, HTTPS_PROXY, and NO_PROXY, which are standard for the Go net/http client.
Linux / macOS (bash/zsh):
export HTTP_PROXY=http://user:password@proxy-host:3128 export HTTPS_PROXY=http://user:password@proxy-host:3128 export NO_PROXY=localhost,127.0.0.1,gitlab.company.com
To avoid typing this every time, add the lines to ~/.bashrc, ~/.zshrc, or ~/.profile.
Windows (PowerShell):
$env:HTTP_PROXY = "http://user:password@proxy-host:3128" $env:HTTPS_PROXY = "http://user:password@proxy-host:3128" $env:NO_PROXY = "localhost,127.0.0.1"
For permanent saving on Windows, use setx:
setx HTTP_PROXY "http://user:password@proxy-host:3128" setx HTTPS_PROXY "http://user:password@proxy-host:3128"
Important: NO_PROXY must include internal domains (internal GitLab, local Athens server), otherwise requests to them will also go through the external proxy and will fail with an access error.
If the public GOPROXY is unavailable not due to an internal firewall but due to geo-blocking in a specific region — a situation faced by teams with servers spread across different countries — instead of a corporate HTTP proxy, you can set up an outgoing tunnel through an external proxy server with the desired geolocation. For such scenarios, data center proxies are suitable — they provide a stable fast channel and predictable latency, which is critical when bulk downloading dependencies in a CI pipeline.
SOCKS5 proxies and bypassing restrictions
The HTTP_PROXY/HTTPS_PROXY variables support not only HTTP(S) proxies but also SOCKS5 — starting with Go 1.10+, the standard library can work through the socks5:// scheme:
export ALL_PROXY=socks5://user:password@proxy-host:1080 export HTTP_PROXY=socks5://user:password@proxy-host:1080 export HTTPS_PROXY=socks5://user:password@proxy-host:1080
The ALL_PROXY variable is universal; many CLI utilities read it, not just Go. If you already have a SOCKS5 tunnel (for example, via SSH: ssh -D 1080 user@remote-host), you can route all go get traffic through it without additional server configuration.
To test builds from different regions (for example, to see how the CI pipeline behaves when requesting a regional package mirror or how an external service responds to requests from a specific country), you often need a channel with a real IP address that resembles a regular user, not a data center. In such cases, residential proxies are chosen — they are less likely to trigger automatic restrictions on the server-side of module distribution.
You can check that the proxy is actually being used by Go with a simple command that provides detailed output:
GODEBUG=http2debug=1 go get -x github.com/gin-gonic/gin
The -x flag prints each command executed, including network requests, which helps to understand whether go get is actually going through the proxy or ignoring the environment variables (this happens if the variables are exported in another terminal session or not passed to the subprocess).
Proxies in CI/CD and Docker
In CI runners (GitHub Actions, GitLab CI, Jenkins), environment variables need to be explicitly passed through job settings, rather than relying on the local .bashrc, which is not read in the container.
GitLab CI (.gitlab-ci.yml):
variables:
GOPROXY: "https://goproxy.cn,direct"
GOPRIVATE: "gitlab.company.com/*"
HTTPS_PROXY: "http://user:password@proxy-host:3128"
build:
script:
- go mod download
- go build ./...
Dockerfile (multi-stage build):
FROM golang:1.22 AS builder
ARG HTTP_PROXY
ARG HTTPS_PROXY
ENV HTTP_PROXY=${HTTP_PROXY}
ENV HTTPS_PROXY=${HTTPS_PROXY}
ENV GOPROXY=https://goproxy.cn,direct
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN go build -o app .
Build arguments are passed when calling docker build:
docker build --build-arg HTTP_PROXY=http://user:password@proxy-host:3128 \ --build-arg HTTPS_PROXY=http://user:password@proxy-host:3128 \ -t myapp .
If the build is running in parallel on multiple runners and you need to avoid being banned by the module mirror due to a large number of simultaneous requests (which can happen with self-hosted Athens proxies under high load), it is useful to spread outgoing requests through IP rotation. To evenly distribute the load and avoid rate-limiting from the module mirror proxy server, data center proxies are often used — they provide low latency, which is important for CI, where every extra second multiplies by the number of jobs.
Common errors and their solutions
| Error | Cause | Solution |
|---|---|---|
dial tcp: i/o timeout |
proxy.golang.org is unavailable from the network | Change GOPROXY to a mirror or configure HTTP_PROXY |
410 Gone |
Private module is unavailable to the public proxy | Configure GOPRIVATE for the required module path |
checksum mismatch |
GOSUMDB is trying to verify a private module | Disable via GONOSUMDB or GOSUMDB=off |
x509: certificate signed by unknown authority |
Corporate proxy replaces the TLS certificate (MITM) | Add the company's root certificate to the system store |
repository not found |
No access token for the private git repository | Configure git config url.insteadOf with the token |
| Proxy variables are ignored | Export was done in another shell/session | Check via env | grep PROXY in the same session where go is run |
It is worth mentioning separately about MITM proxies (corporate Squid/Zscaler with certificate replacement): if such a proxy intercepts HTTPS traffic for analysis, the Go client does not trust its self-signed certificate, leading to the x509 error. The solution is to export the company's root certificate in PEM format and specify it in the variable:
export SSL_CERT_FILE=/etc/ssl/certs/company-root-ca.pem
This variable is read by the Go runtime when checking the TLS chain and allows working through the corporate MITM proxy without completely disabling certificate verification (which should not be done for security reasons).
Conclusion
If Go modules are not downloading, in 90% of cases, three steps are sufficient: set a working GOPROXY (a public mirror instead of the blocked proxy.golang.org), add GOPRIVATE for internal repositories, and specify HTTP_PROXY/HTTPS_PROXY if the network goes out only through a corporate proxy. For CI/CD, these variables need to be explicitly passed through job environment variables or Docker build arguments, rather than relying on local developer configs.
If the cause of failures is geo-blocking of the module mirror or rate-limiting from the proxy server during parallel builds in CI, it is advisable to route outgoing traffic through a stable external channel. For such tasks, data center proxies are well-suited — low latency and predictable bandwidth are critical when bulk downloading dependencies. And if you need to emulate regular user traffic when testing the availability of external services from different regions, residential proxies will do — they are less likely to raise suspicions with protection systems on the module distribution server side.