valyala/fasthttp · error

cannot determine tls server name from addr %q: %w

Error message

cannot determine tls server name from addr %q: %w

What it means

When building the TLS config for a connection, fasthttp must derive the TLS ServerName (for SNI and certificate verification) from the dial address. If tlsServerName fails (e.g. the addr is an IP or unparseable) and no ServerName is configured and InsecureSkipVerify is false, this error is returned.

Source

Thrown at client.go:2201

	} else {
		c.readerPool.Put(br)
	}
}

func newClientTLSConfig(c *tls.Config, addr string) (*tls.Config, error) {
	if c == nil {
		c = &tls.Config{}
	} else {
		c = c.Clone()
	}

	if c.ServerName == "" {
		serverName, err := tlsServerName(addr)
		if err != nil {
			if c.InsecureSkipVerify {
				return c, nil
			}
			return nil, fmt.Errorf("cannot determine tls server name from addr %q: %w", addr, err)
		}
		c.ServerName = serverName
	}
	return c, nil
}

func tlsServerName(addr string) (string, error) {
	if !strings.Contains(addr, ":") {
		return addr, nil
	}
	host, _, err := net.SplitHostPort(addr)
	if err != nil {
		return "", err
	}
	return host, nil
}

func (c *HostClient) nextAddr() string {

View on GitHub (pinned to c96f600972)

Solutions

1. Set TLSConfig.ServerName explicitly to the certificate's DNS name
2. Dial using the hostname instead of the IP
3. If this is intentional (dev/test), set InsecureSkipVerify: true in TLSConfig (never in production)
4. Provide a custom TLSConfig via HostClient.TLSConfig with proper RootCAs

Example fix

// before
hc := &fasthttp.HostClient{Addr: "10.0.0.5:443", IsTLS: true} // no ServerName
// after
hc := &fasthttp.HostClient{
    Addr:  "10.0.0.5:443",
    IsTLS: true,
    TLSConfig: &tls.Config{ServerName: "api.example.com"},
}

if net.ParseIP(hostOnly(addr)) != nil && tlsCfg.ServerName == "" {
    return errors.New("dialing TLS by IP requires TLSConfig.ServerName")
}

c, err := client.Do(req, resp) // or dial
if err != nil {
    if strings.Contains(err.Error(), "cannot determine tls server name") {
        // retry with a HostClient that sets TLSConfig.ServerName
    }
}

When it happens

Trigger: Dialing an HTTPS host by raw IP address, or an address string that cannot yield a DNS name, while TLS verification is enabled and TLSConfig.ServerName is empty.

Common situations: Connecting to https://127.0.0.1:8443 or https://10.0.0.5 in dev/test environments, service discovery returning IPs, custom dialers passing odd address formats.

Understand the failure class

• SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

• must implement readat
• directory index required
• no 'create file' permissions
• seek is not implemented
• fasthttp: contain forbidden trailer

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