CI "TLS handshake timeout" - Fix Slow/Failed TLS on Runners

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.

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

1. Re-run the step - a one-off handshake stall clears on retry.
2. Increase the client TLS/connection timeout for tools that allow it.
3. 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.

env | grep -i proxy
curl -v --connect-timeout 10 https://registry.example.com/v2/ 2>&1 | head

How to prevent it

• Retry TLS-dependent steps with backoff.
• Mirror or cache registries to reduce handshake round trips.
• Account for proxy latency when setting connection timeouts.

Related guides