{"record":{"id":"85199bc85a38e553","repo":"valyala/fasthttp","slug":"fasthttp-dialing-to-the-given-tcp-address-timed-o","errorCode":null,"errorMessage":"fasthttp: dialing to the given tcp address timed out","messagePattern":"fasthttp: dialing to the given tcp address timed out","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"tcpdialer.go","lineNumber":374,"sourceCode":"\tdialer := net.Dialer{}\n\tif d.LocalAddr != nil {\n\t\tdialer.LocalAddr = d.LocalAddr\n\t}\n\n\tctx, cancelCtx := context.WithDeadline(context.Background(), deadline)\n\tdefer cancelCtx()\n\tconn, err := dialer.DialContext(ctx, network, addr)\n\tif err != nil {\n\t\tif ctx.Err() == context.DeadlineExceeded {\n\t\t\treturn nil, wrapDialWithUpstream(ErrDialTimeout, addr)\n\t\t}\n\t\treturn nil, wrapDialWithUpstream(err, addr)\n\t}\n\treturn conn, nil\n}\n\n// ErrDialTimeout is returned when TCP dialing is timed out.\nvar ErrDialTimeout = errors.New(\"fasthttp: dialing to the given tcp address timed out\")\n\n// ErrDialWithUpstream wraps dial error with upstream info.\n//\n// Should use errors.As to get upstream information from error:\n//\n//\thc := fasthttp.HostClient{Addr: \"foo.com,bar.com\"}\n//\terr := hc.Do(req, res)\n//\n//\tvar dialErr *fasthttp.ErrDialWithUpstream\n//\tif errors.As(err, &dialErr) {\n//\t\tupstream = dialErr.Upstream // 34.206.39.153:80\n//\t}\ntype ErrDialWithUpstream struct {\n\twrapErr  error\n\tUpstream string\n}\n\nfunc (e *ErrDialWithUpstream) Error() string {","sourceCodeStart":356,"sourceCodeEnd":392,"githubUrl":"https://github.com/valyala/fasthttp/blob/c96f600972c6f4a7a30d664257b340ebe9d60124/tcpdialer.go#L356-L392","documentation":"ErrDialTimeout is exported by fasthttp and returned when establishing a TCP connection times out, i.e. dialing to the given address exceeded the configured DialDoubleCheckTimeout / client timeout before the connection could be established.","triggerScenarios":"HostClient/Client Do or Get against a host whose TCP connect exceeds the dial timeout (default ~ dial timeout in tcpdialer), including when DialTimeout/WriteTimeout constraints on the client are tighter than network latency.","commonSituations":"Calling slow or unreachable upstream services; firewalled ports that drop SYN packets (silent drop causes timeout rather than refusal); DNS resolving but host not responding.","solutions":["Increase the client's timeout/Dial timeout to accommodate slow networks.","Verify network reachability to the target host/port (firewall rules, routing).","Use retry with backoff around requests; consider fasthttp's built-in retry via Client.RetryIf.","Prefer ErrDialTimeout checking with errors.Is to distinguish from other dial failures."],"exampleFix":"// before\nclient := &fasthttp.Client{}\nstatusCode, body, err := client.Get(nil, \"http://slow-host/\")\n// after\nclient := &fasthttp.Client{ Dial: (&fasthttp.TCPDialer{ Timeout: 10 * time.Second }).Dial }\nstatusCode, body, err := client.Get(nil, \"http://slow-host/\")\nif errors.Is(err, fasthttp.ErrDialTimeout) { /* retry or alert */ }","handlingStrategy":"retry","validationCode":"// Before dialing, verify the host:port is configured and resolvable\nif _, _, err := net.SplitHostPort(addr); err != nil {\n    return fmt.Errorf(\"invalid dial address %q: %w\", addr, err)\n}","typeGuard":"func isDialTimeout(err error) bool {\n    return errors.Is(err, fasthttp.ErrDialTimeout)\n}","tryCatchPattern":"statusCode, body, err := client.Get(nil, url)\nif isDialTimeout(err) {\n    // backoff and retry, or fail over to another upstream\n    return retry(url)\n}","preventionTips":["Set an explicit TCPDialer.Timeout appropriate for your network.","Distinguish ErrDialTimeout from other dial errors with errors.Is before retrying.","Monitor upstream latency; alert before timeouts become routine.","Check firewall/security-group rules for silently dropped SYN packets."],"tags":["network","timeout","dial","tcp"],"backgroundTag":"dial-timeout","analyzedSha":"c96f600972c6f4a7a30d664257b340ebe9d60124","analyzedAt":"2026-08-31T22:48:28.265Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}