go network_error ai_generated partial

net/http: TLS handshake timeout

ID: go/tls-handshake-timeout

Also available as: JSON · Markdown
78%Fix Rate
82%Confidence
50Evidence
2023-01-01First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
1 active — — —

Root Cause

The TLS handshake did not complete within the configured timeout. Causes include slow DNS, network congestion, misconfigured TLS, or connecting to a non-TLS port with a TLS client.

generic

Workarounds

  1. 85% success Increase TLSHandshakeTimeout on the HTTP transport 
    client := &http.Client{
    Transport: &http.Transport{
        TLSHandshakeTimeout: 15 * time.Second,
    },
}

    Sources: https://pkg.go.dev/net/http#Transport

  2. 80% success Verify the target server supports the TLS version your client offers 
    Set tls.Config MinVersion and MaxVersion to match server capabilities. Use openssl s_client -connect host:port to diagnose.

    Sources: https://pkg.go.dev/crypto/tls#Config

Dead Ends

Common approaches that don't work:

  1. Set InsecureSkipVerify=true on TLS config 90% fail

    InsecureSkipVerify skips certificate validation but does not fix handshake timeouts — the timeout occurs before certificate verification

  2. Downgrade to HTTP instead of HTTPS 80% fail

    Removes transport security entirely — only masks the problem

Error Chain

Leads to:
Preceded by:
Frequently confused with: