valyala/fasthttp · error

invalid ipv6 address

Error message

invalid ipv6 address

What it means

After host/zone checks pass, validateIPv6Literal validates the actual IPv6 address bytes inside the brackets. errInvalidIPv6Address is returned when the address itself cannot be parsed — wrong number of groups, invalid hex digits, bad embedded IPv4, or misplaced '::'.

Source

Thrown at ipv6.go:11

package fasthttp

import (
	"bytes"
	"errors"
)

var (
	errInvalidIPv6Host    = errors.New("invalid ipv6 host")
	errInvalidIPv6Zone    = errors.New("invalid ipv6 zone")
	errInvalidIPv6Address = errors.New("invalid ipv6 address")
)

func validateIPv6Literal(host []byte) error {
	if len(host) == 0 || host[0] != '[' {
		return nil
	}
	end := bytes.IndexByte(host, ']')
	if end < 0 || end == 1 {
		return errInvalidIPv6Host
	}
	addr := host[1:end]

	// Optional zone.
	if zi := bytes.IndexByte(addr, '%'); zi >= 0 {
		if zi == len(addr)-1 {
			return errInvalidIPv6Zone
		}
		addr = addr[:zi]

View on GitHub (pinned to c96f600972)

Solutions

1. Correct the address syntax (validate with net.ParseIP after stripping brackets before use).
2. Resolve hostnames to IPs and format with net.IP.String() wrapped in brackets instead of hand-writing addresses.
3. Use URI.Parse with a full URL and handle the error to catch malformed literals early.

Example fix

// before
req.Header.SetHost("[1:2:3]") // invalid ipv6 address
// after
ip := net.ParseIP("fd00::1")
req.Header.SetHost("[" + ip.String() + "]") // "[fd00::1]"

func validIPv6Addr(host string) bool {
    inner := strings.TrimSuffix(strings.TrimPrefix(host, "["), "]")
    if i := strings.IndexByte(inner, '%'); i >= 0 {
        inner = inner[:i]
    }
    ip := net.ParseIP(inner)
    return ip != nil && strings.Contains(inner, ":")
}

When it happens

Trigger: Setting a host such as '[zz::1]', '[1:2:3]' (too few groups, no ::), '[::1::2]' (multiple '::'), or '[1.2.3.4]' through URI parsing / SetHost paths.

Common situations: Typos when hardcoding IPv6 endpoints in config; interpolating variables into host strings; DNS returning unexpected literals that code blindly brackets before passing to fasthttp.

Related errors

• invalid ipv6 host
• invalid ipv6 zone
• invalid port %q after host
• couldn't find dns entries for the given domain: try using du
• value is negative, cannot convert to uint32

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