{"record":{"id":"694e1155ee088013","repo":"valyala/fasthttp","slug":"fasthttp-tls-handshake-timed-out","errorCode":null,"errorMessage":"fasthttp: tls handshake timed out","messagePattern":"fasthttp: tls handshake timed out","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client.go","lineNumber":2295,"sourceCode":"\t\tc.tlsConfigMap = make(map[string]*tls.Config)\n\t}\n\tcfg := c.tlsConfigMap[addr]\n\tif cfg == nil {\n\t\tvar err error\n\t\tcfg, err = newClientTLSConfig(c.TLSConfig, addr)\n\t\tif err != nil {\n\t\t\tc.tlsConfigMapLock.Unlock()\n\t\t\treturn nil, err\n\t\t}\n\t\tc.tlsConfigMap[addr] = cfg\n\t}\n\tc.tlsConfigMapLock.Unlock()\n\n\treturn cfg, nil\n}\n\n// ErrTLSHandshakeTimeout indicates there is a timeout from tls handshake.\nvar ErrTLSHandshakeTimeout = errors.New(\"fasthttp: tls handshake timed out\")\n\nfunc tlsClientHandshake(rawConn net.Conn, tlsConfig *tls.Config, deadline time.Time) (_ net.Conn, retErr error) {\n\tdefer func() {\n\t\tif retErr != nil {\n\t\t\trawConn.Close()\n\t\t}\n\t}()\n\tconn := tls.Client(rawConn, tlsConfig)\n\terr := conn.SetDeadline(deadline)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\terr = conn.Handshake()\n\tif netErr, ok := err.(net.Error); ok && netErr.Timeout() {\n\t\treturn nil, ErrTLSHandshakeTimeout\n\t}\n\tif err != nil {\n\t\treturn nil, err","sourceCodeStart":2277,"sourceCodeEnd":2313,"githubUrl":"https://github.com/valyala/fasthttp/blob/c96f600972c6f4a7a30d664257b340ebe9d60124/client.go#L2277-L2313","documentation":"ErrTLSHandshakeTimeout indicates the TLS handshake with the remote host exceeded its deadline (Client.TLSHandshakeTimeout). fasthttp aborts the connection rather than waiting indefinitely on a stalled handshake.","triggerScenarios":"TLS requests where the server accepts the TCP connection but the handshake does not complete within TLSHandshakeTimeout; very slow networks or overloaded TLS terminators.","commonSituations":"Targets behind saturated load balancers; high-latency links with a very small TLSHandshakeTimeout; blackholed network paths where TCP connects but TLS stalls.","solutions":["Increase Client.TLSHandshakeTimeout to fit your network latency","Check the network path and server TLS termination health","Retry with backoff on ErrTLSHandshakeTimeout via Client.RetryIf or caller-side retry","Reduce load on the TLS terminator or move to a faster endpoint/CDN"],"exampleFix":"// before\nc := &fasthttp.Client{TLSHandshakeTimeout: 100 * time.Millisecond} // too tight for WAN\n// after\nc := &fasthttp.Client{TLSHandshakeTimeout: 10 * time.Second}","handlingStrategy":"retry","validationCode":"if client.TLSHandshakeTimeout < 5*time.Second {\n    client.TLSHandshakeTimeout = 10 * time.Second\n}","typeGuard":null,"tryCatchPattern":"if errors.Is(err, fasthttp.ErrTLSHandshakeTimeout) {\n    time.Sleep(backoff)\n    return do(req, resp) // bounded retry\n}","preventionTips":["Set TLSHandshakeTimeout generously for WAN/high-latency targets","Monitor TLS termination health on the server/LB","Test handshake latency with openssl s_client regularly","Retry with backoff via Client.RetryIf"],"tags":["tls","timeout","network","client"],"backgroundTag":"tls-handshake-timeout","analyzedSha":"c96f600972c6f4a7a30d664257b340ebe9d60124","analyzedAt":"2026-08-31T22:48:28.265Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}