valyala/fasthttp · error

invalid ipv6 zone

Error message

invalid ipv6 zone

What it means

When parsing a bracketed IPv6 literal host, fasthttp validates the zone part (the %zone suffix inside the brackets, e.g. [fe80::1%eth0]). errInvalidIPv6Zone is returned if the zone identifier is malformed — empty zone, invalid characters, or trailing garbage after the zone.

Source

Thrown at ipv6.go:10

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
		}

View on GitHub (pinned to c96f600972)

Solutions

1. Provide a valid, non-empty zone inside the brackets: '[fe80::1%eth0]'.
2. Drop the zone if it is not needed (most HTTP usages: use '[fe80::1]').
3. Parse the full URL with fasthttp's URI.Parse instead of manual host assembly so errors point at the exact problem.

Example fix

// before
u := &fasthttp.URI{}
u.Parse(nil, []byte("http://[fe80::1%]/")) // invalid ipv6 zone
// after
u := &fasthttp.URI{}
u.Parse(nil, []byte("http://[fe80::1%eth0]/"))

func validZone(host string) bool {
    if !strings.HasSuffix(host, "]") || !strings.Contains(host, "%") {
        return strings.HasSuffix(host, "]")
    }
    inner := strings.TrimSuffix(strings.TrimPrefix(host, "["), "]")
    i := strings.IndexByte(inner, '%')
    return i > 0 && i < len(inner)-1 && !strings.Contains(inner[i+1:], "]")
}

When it happens

Trigger: Setting a host like '[fe80::1%]' (empty zone), '[fe80::1%zone]extra', or with invalid zone characters through URI host parsing / SetHost / validateIPv6Literal.

Common situations: Building link-local URIs with zone identifiers by hand; copying scoped addresses from OS output (e.g. 'fe80::1%en0') and pasting them into URIs incorrectly; proxies forwarding zone-qualified hosts.

Related errors

• invalid ipv6 host
• invalid ipv6 address
• unexpected convert net interface index int to uint32: %w
• invalid port %q after host
• couldn't find dns entries for the given domain: try using du

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