valyala/fasthttp · error

fasthttp: dialing to the given tcp address timed out

Error message

fasthttp: dialing to the given tcp address timed out

What it means

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.

Source

Thrown at tcpdialer.go:374

	dialer := net.Dialer{}
	if d.LocalAddr != nil {
		dialer.LocalAddr = d.LocalAddr
	}

	ctx, cancelCtx := context.WithDeadline(context.Background(), deadline)
	defer cancelCtx()
	conn, err := dialer.DialContext(ctx, network, addr)
	if err != nil {
		if ctx.Err() == context.DeadlineExceeded {
			return nil, wrapDialWithUpstream(ErrDialTimeout, addr)
		}
		return nil, wrapDialWithUpstream(err, addr)
	}
	return conn, nil
}

// ErrDialTimeout is returned when TCP dialing is timed out.
var ErrDialTimeout = errors.New("fasthttp: dialing to the given tcp address timed out")

// ErrDialWithUpstream wraps dial error with upstream info.
//
// Should use errors.As to get upstream information from error:
//
//	hc := fasthttp.HostClient{Addr: "foo.com,bar.com"}
//	err := hc.Do(req, res)
//
//	var dialErr *fasthttp.ErrDialWithUpstream
//	if errors.As(err, &dialErr) {
//		upstream = dialErr.Upstream // 34.206.39.153:80
//	}
type ErrDialWithUpstream struct {
	wrapErr  error
	Upstream string
}

func (e *ErrDialWithUpstream) Error() string {

View on GitHub (pinned to c96f600972)

Solutions

1. Increase the client's timeout/Dial timeout to accommodate slow networks.
2. Verify network reachability to the target host/port (firewall rules, routing).
3. Use retry with backoff around requests; consider fasthttp's built-in retry via Client.RetryIf.
4. Prefer ErrDialTimeout checking with errors.Is to distinguish from other dial failures.

Example fix

// before
client := &fasthttp.Client{}
statusCode, body, err := client.Get(nil, "http://slow-host/")
// after
client := &fasthttp.Client{ Dial: (&fasthttp.TCPDialer{ Timeout: 10 * time.Second }).Dial }
statusCode, body, err := client.Get(nil, "http://slow-host/")
if errors.Is(err, fasthttp.ErrDialTimeout) { /* retry or alert */ }

// Before dialing, verify the host:port is configured and resolvable
if _, _, err := net.SplitHostPort(addr); err != nil {
    return fmt.Errorf("invalid dial address %q: %w", addr, err)
}

func isDialTimeout(err error) bool {
    return errors.Is(err, fasthttp.ErrDialTimeout)
}

statusCode, body, err := client.Get(nil, url)
if isDialTimeout(err) {
    // backoff and retry, or fail over to another upstream
    return retry(url)
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• fasthttp: tls handshake timed out
• couldn't find dns entries for the given domain: try using du
• only tcp, tcp4, or tcp6 is supported
• value is negative, cannot convert to uintptr
• cannot disable nagle's algorithm: %w

AI-assisted analysis of valyala/fasthttp@c96f600972 (2026-08-31). Data as JSON: /api/errors/85199bc85a38e553. Report an issue: GitHub.