XTLS/Xray-core · error

failed to parse address and port

Error message

failed to parse address and port

What it means

FrameMetadata.Unmarshal could not decode the target address+port of a mux frame using addrParser.ReadAddressPort. This means the bytes following the session/network header of a SessionStatusNew frame (or a Keep frame carrying a UDP target) are not a valid Xray address format (IPv4/IPv6/domain + port). It almost always indicates a corrupted stream or a peer speaking an incompatible mux protocol.

Source

Thrown at common/mux/frame.go:154

		return errors.New("insufficient buffer: ", b.Len())
	}

	f.SessionID = binary.BigEndian.Uint16(b.BytesTo(2))
	f.SessionStatus = SessionStatus(b.Byte(2))
	f.Option = bitmask.Byte(b.Byte(3))
	f.Target.Network = net.Network_Unknown

	if f.SessionStatus == SessionStatusNew || (f.SessionStatus == SessionStatusKeep && b.Len() > 4 &&
		TargetNetwork(b.Byte(4)) == TargetNetworkUDP) { // MUST check the flag first
		if b.Len() < 8 {
			return errors.New("insufficient buffer: ", b.Len())
		}
		network := TargetNetwork(b.Byte(4))
		b.Advance(5)

		addr, port, err := addrParser.ReadAddressPort(nil, b)
		if err != nil {
			return errors.New("failed to parse address and port").Base(err)
		}

		switch network {
		case TargetNetworkTCP:
			f.Target = net.TCPDestination(addr, port)
		case TargetNetworkUDP:
			f.Target = net.UDPDestination(addr, port)
		default:
			return errors.New("unknown network type: ", network)
		}
	}

	if f.SessionStatus == SessionStatusNew && readSourceAndLocal {
		f.Inbound = &session.Inbound{}

		if b.Len() == 0 {
			return nil // for heartbeat, etc.
		}

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Verify both endpoints run the same (latest) Xray-core version so frame encoding matches.
2. Confirm the client actually enabled Mux on the outbound and the server expects it (mux is negotiated per-inbound; mismatched wiring feeds raw bytes to the frame parser).
3. Disable Mux temporarily on the outbound to confirm the connection itself is healthy; if it works, the problem is frame encoding, not transport.
4. If you maintain a custom client, check the bytes you write for SessionStatusNew: network byte (offset 4), then address, then port, in Xray address format.
5. Capture the stream and inspect the frame at the failure offset to see whether the payload is mux metadata or unrelated data.

Example fix

// client config (JSON): make sure mux is only enabled when the server supports it
// before
"outbounds": [{ "protocol": "vless", "settings": {}, "streamSettings": { "mux": { "enabled": true } } }]
// after: same version on both sides and correct address encoding
"outbounds": [{ "protocol": "vless", "settings": {}, "streamSettings": { "mux": { "enabled": true, "concurrency": 8 } } }]

// In Go, treat frame parse errors as fatal for the mux connection:
if err := meta.Unmarshal(reader, isReverse); err != nil {
    // close the whole mux connection; do not retry parsing the same stream
    cancel()
    log.Warn("mux frame unmarshal failed, closing connection: ", err)
}

When it happens

Trigger: A Mux (or XUDP Keep) frame arrives where the address section is truncated, garbled, or encoded by a different/older mux implementation; feeding a non-mux stream (e.g. plain proxy traffic or TLS handshake bytes) into a Mux ServerWorker also produces it.

Common situations: Version mismatch between client and server mux implementations, a middlebox corrupting the stream, connecting a mux-enabled inbound to a non-mux outbound, or bugs in custom clients that hand-craft frame metadata.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• failed to read metadata
• invalid metalen
• insufficient buffer:
• unknown network type:
• reading source: failed to parse address and port

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