XTLS/Xray-core · error

unknown address type: {addrType}

Error message

unknown address type: {addrType}

What it means

Returned while decoding a proxied address header when the first address-type byte is >= 16. The protocol allocates only 0-15 for known address types (IPv4/IPv6/domain plus optional padding types), so anything at or above 16 is by definition unknown and the message is considered malformed.

Source

Thrown at common/protocol/address.go:185

type addressParser struct {
	addrTypeMap [16]net.AddressFamily
	addrByteMap [16]byte
	typeParser  AddressTypeParser
}

func (p *addressParser) readAddress(b *buf.Buffer, reader io.Reader) (net.Address, error) {
	if _, err := b.ReadFullFrom(reader, 1); err != nil {
		return nil, err
	}

	addrType := b.Byte(b.Len() - 1)
	if p.typeParser != nil {
		addrType = p.typeParser(addrType)
	}

	if addrType >= 16 {
		return nil, errors.New("unknown address type: ", addrType)
	}

	addrFamily := p.addrTypeMap[addrType]
	if addrFamily == net.AddressFamily(afInvalid) {
		return nil, errors.New("unknown address type: ", addrType)
	}

	switch addrFamily {
	case net.AddressFamilyIPv4:
		if _, err := b.ReadFullFrom(reader, 4); err != nil {
			return nil, err
		}
		return net.IPAddress(b.BytesFrom(-4)), nil
	case net.AddressFamilyIPv6:
		if _, err := b.ReadFullFrom(reader, 16); err != nil {
			return nil, err
		}
		return net.IPAddress(b.BytesFrom(-16)), nil

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Verify client and server use the identical protocol, version, and credentials
2. Confirm nothing else (load balancer, CDN, monitoring probe) is injecting bytes into the stream
3. Capture the first bytes of the connection to confirm the framing matches the expected proxy protocol header

addr, err := parser.ReadAddress(buf, reader)
if err != nil {
    conn.Close() // framing is unrecoverable; drop the connection
    log.Debug("malformed address header: ", err)
}

When it happens

Trigger: readAddress reading a stream that is not actually a proxy protocol message: garbage bytes after a protocol mismatch, an encrypted stream decrypted with the wrong key/AEAD mismatch, or a framing desync that makes a length byte be interpreted as the type byte.

Common situations: Client and server configured with different protocols on the same port, wrong decryption (altered UUID/secret or password), or a health-checker/monitor sending plain HTTP to a proxy inbound.

Related errors

• varint overflow
• invalid body length:
• failed to parse address and port
• failed to read metadata
• invalid domain name: {domain}

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