XTLS/Xray-core · error

reading local: failed to parse address and port

Error message

reading local: failed to parse address and port

What it means

While unmarshalling the optional inbound local-address block (the second optional address after the source address, only when readSourceAndLocal is true), addrParser.ReadAddressPort failed. The frame's trailing bytes claim to be a local address but do not decode as one.

Source

Thrown at common/mux/frame.go:201

		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)
		addr, port, err = addrParser.ReadAddressPort(nil, b)
		if err != nil {
			return errors.New("reading local: failed to parse address and port").Base(err)
		}
		switch network {
		case TargetNetworkTCP:
			f.Inbound.Local = net.TCPDestination(addr, port)
		case TargetNetworkUDP:
			f.Inbound.Local = net.UDPDestination(addr, port)
		default:
			return errors.New("reading local: unknown network type: ", network)
		}

		return nil
	}

	// Application data is essential, to test whether the pipe is closed.
	if f.SessionStatus == SessionStatusNew && f.Option.Has(OptionData) &&
		f.Target.Network == net.Network_UDP && b.Len() >= 8 {
		copy(f.GlobalID[:], b.Bytes())
	}

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Match Xray-core versions across the reverse-mux tunnel.
2. Verify the client writes a 0 byte (padding) when it has no local address to send.
3. Hexdump the failing frame tail to check for unexpected padding.
4. Disable the feature/path that sets readSourceAndLocal to confirm the diagnosis.

if err := meta.Unmarshal(reader, true); err != nil {
    return err // stream trust is gone; close the connection

When it happens

Trigger: A SessionStatusNew frame with readSourceAndLocal=true where, after a valid source address, the next non-zero network byte is followed by a malformed address; also happens when extra trailing bytes (padding written by a different version) are mistaken for a local address block.

Common situations: Reverse-mux interoperability between different Xray versions, or clients that append arbitrary padding after the source address.

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 source: 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/ca5fd044171c30ae. Report an issue: GitHub.