CI "TLS handshake timeout" - Fix Slow/Failed TLS on Runners
By Kaveh Alemi·Latchkey
The TCP connection opened but the TLS handshake never finished in time. The negotiation stalled - usually because the remote was briefly overloaded or the link was congested - so the client gave up.
What this error means
A go get, docker pull, or HTTPS download fails with TLS handshake timeout. The connection reached the server (so it is not DNS), but securing it stalled. Re-running typically succeeds.
CI log
net/http: TLS handshake timeout
# or
Get "https://registry.example.com/v2/": net/http: TLS handshake timeout
Common causes
The remote was briefly overloaded or congested
TLS negotiation is round-trip heavy. A momentarily slow server or a congested path makes the handshake exceed the client timeout, even though the endpoint is reachable.
A proxy or MITM inspecting TLS added latency
A corporate proxy terminating and re-establishing TLS adds round trips. Under load that extra latency can push the handshake past its deadline.
How to fix it
Retry and raise the handshake timeout
Re-run the step - a one-off handshake stall clears on retry.
Increase the client TLS/connection timeout for tools that allow it.
Pull through a closer mirror or pull-through cache to cut latency.
Rule out a slow proxy
Check whether a proxy is in the path and adding round trips.
Mirror or cache registries to reduce handshake round trips.
Account for proxy latency when setting connection timeouts.
Frequently asked questions
What causes ""TLS handshake timeout""?
TLS negotiation is round-trip heavy. A momentarily slow server or a congested path makes the handshake exceed the client timeout, even though the endpoint is reachable.
How do I fix "TLS handshake timeout"?
Retry and raise the handshake timeout
Can Latchkey fix this automatically?
Yes. Latchkey runs your GitHub Actions on managed runners that detect this failure, apply the fix, and retry the job automatically - self-healing is on by default.
