XTLS/Xray-core · error

unknown network type:

Error message

unknown network type: 

What it means

After successfully parsing an address in FrameMetadata.Unmarshal, the target network byte was neither TargetNetworkTCP nor TargetNetworkUDP. The address section is fine but the leading network-type byte holds an undefined value (anything other than the two defined flags), so the destination transport cannot be constructed.

Source

Thrown at common/mux/frame.go:163

		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.
		}
		network := TargetNetwork(b.Byte(0))
		if network == 0 {
			return nil // may be padding
		}
		b.Advance(1)
		addr, port, err := addrParser.ReadAddressPort(nil, b)
		if err != nil {
			return errors.New("reading source: failed to parse address and port").Base(err)
		}

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Print/inspect the offending network byte (it is included in the message) to see if it is random garbage (corruption) or a fixed value (protocol mismatch).
2. Align client and server Xray-core versions.
3. If writing a custom mux client, emit only TargetNetworkTCP or TargetNetworkUDP in the target network byte.
4. Rule out stream corruption by testing the same link without TLS/Reality or over a known-clean network.

// Before unmarshalling (custom readers), sanity-check the network byte:
if n := TargetNetwork(b.Byte(4)); n != TargetNetworkTCP && n != TargetNetworkUDP {
    return fmt.Errorf("unsupported target network byte %d", n)
}

if err := meta.Unmarshal(reader, rev); err != nil {
    if strings.Contains(err.Error(), "unknown network type") { /* protocol mismatch: abort connection, log peer version */ }
    return err
}

When it happens

Trigger: A frame's byte at offset 4 (target network) is a value like 0x02+ or garbage; happens with hand-rolled mux clients, stream corruption, or when a non-mux stream is parsed as frames.

Common situations: Custom client implementations that invent new network flags, protocol regressions between Xray versions, or bit corruption on the wire.

Related errors

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

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