XTLS/Xray-core · error

unknown address family{family}

Error message

unknown address family{family}

What it means

Returned by writeAddress when the address family of the address being serialized has no byte mapping in addrByteMap (afInvalid). The writer cannot encode an address whose family the protocol header format does not define (only IPv4, IPv6, and Domain are encodable).

Source

Thrown at common/protocol/address.go:231

		if maybeIPPrefix(domain[0]) {
			addr := net.ParseAddress(domain)
			if addr.Family().IsIP() {
				return addr, nil
			}
		}
		if !isValidDomain(domain) {
			return nil, errors.New("invalid domain name: ", domain)
		}
		return net.DomainAddress(domain), nil
	default:
		panic("impossible case")
	}
}

func (p *addressParser) writeAddress(writer io.Writer, address net.Address) error {
	tb := p.addrByteMap[address.Family()]
	if tb == afInvalid {
		return errors.New("unknown address family", address.Family())
	}

	switch address.Family() {
	case net.AddressFamilyIPv4, net.AddressFamilyIPv6:
		if _, err := writer.Write([]byte{tb}); err != nil {
			return err
		}
		if _, err := writer.Write(address.IP()); err != nil {
			return err
		}
	case net.AddressFamilyDomain:
		domain := address.Domain()
		if isDomainTooLong(domain) {
			return errors.New("Super long domain is not supported: ", domain)
		}

		if _, err := writer.Write([]byte{tb, byte(len(domain))}); err != nil {
			return err

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Check address.IsValid()/family before serializing and reject invalid addresses upstream
2. Ensure addresses are always constructed via net.ParseAddress or net.DomainAddress rather than raw structs

Example fix

// before
parser.WriteAddress(writer, addr) // addr may be zero-value

// after
if !addr.IsValid() {
    return errors.New("cannot serialize invalid address")
}
parser.WriteAddress(writer, addr)

func isEncodableAddress(a net.Address) bool {
    f := a.Family()
    return f.IsIP() || f.IsDomain()
}

When it happens

Trigger: Serializing a net.Address whose Family() is neither IPv4, IPv6, nor Domain - e.g. an invalid/zero-value Address, or a future family type - into a proxy protocol header.

Common situations: Passing an uninitialized net.Address or an address built from invalid input into routing/forwarding code that then writes it into a protocol header.

Related errors

• No available name server could be created from
• unknown network type:
• unknown status:
• invalid domain name: {domain}
• Super long domain is not supported: {domain}

AI-assisted analysis of XTLS/Xray-core@7d214f8b09 (2026-08-15). Data as JSON: /api/errors/445626262e9dc507. Report an issue: GitHub.