XTLS/Xray-core · error

reading source: failed to parse address and port

Error message

reading source: failed to parse address and port

What it means

While unmarshalling the optional inbound-source section of a SessionStatusNew frame (only read when readSourceAndLocal is true, e.g. reverse mux), addrParser.ReadAddressPort failed on the source address. The frame carries a source-address block that is not valid Xray address encoding.

Source

Thrown at common/mux/frame.go:180

		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)
		}
		switch network {
		case TargetNetworkTCP:
			f.Inbound.Source = net.TCPDestination(addr, port)
		case TargetNetworkUDP:
			f.Inbound.Source = net.UDPDestination(addr, port)
		default:
			return errors.New("reading source: unknown network type: ", network)
		}

		if b.Len() == 0 {
			return nil
		}
		network = TargetNetwork(b.Byte(0))
		if network == 0 {
			return nil
		}
		b.Advance(1)

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Ensure both ends of the reverse-mux tunnel run the same Xray-core version (source/local encoding changed over time).
2. Reproduce with readSourceAndLocal disabled (non-reverse mux) to isolate whether the optional source block is the problem.
3. Inspect the raw frame bytes: after the target address, the first byte must be 0 (padding/heartbeat) or a valid network byte followed by a well-formed address+port.
4. Check for middleware or obfuscation layers that could reorder/truncate the payload.

if err := meta.Unmarshal(reader, session.IsReverseMuxFromContext(ctx)); err != nil {
    // any source-address parse failure means the stream is unusable
    return err // closes mux connection via run loop
}

When it happens

Trigger: Reverse-mux (or any path passing readSourceAndLocal=true) receives a New frame whose post-metadata bytes begin with a network byte plus a malformed address; also triggered when optional padding/heartbeat bytes are misinterpreted as a source address.

Common situations: Reverse proxy mux where the client version does not write source/local addresses the way the server expects them, or stream corruption inside a reverse-mux tunnel.

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

• reading local: failed to parse address and port
• failed to create mux client worker
• failed to create portal worker
• empty worker list
• no mux client worker available

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