{"record":{"id":"0f7aba0feb005d47","repo":"XTLS/Xray-core","slug":"failed-to-parse-address-and-port","errorCode":null,"errorMessage":"failed to parse address and port","messagePattern":"failed to parse address and port","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"common/mux/frame.go","lineNumber":154,"sourceCode":"\t\treturn errors.New(\"insufficient buffer: \", b.Len())\n\t}\n\n\tf.SessionID = binary.BigEndian.Uint16(b.BytesTo(2))\n\tf.SessionStatus = SessionStatus(b.Byte(2))\n\tf.Option = bitmask.Byte(b.Byte(3))\n\tf.Target.Network = net.Network_Unknown\n\n\tif f.SessionStatus == SessionStatusNew || (f.SessionStatus == SessionStatusKeep && b.Len() > 4 &&\n\t\tTargetNetwork(b.Byte(4)) == TargetNetworkUDP) { // MUST check the flag first\n\t\tif b.Len() < 8 {\n\t\t\treturn errors.New(\"insufficient buffer: \", b.Len())\n\t\t}\n\t\tnetwork := TargetNetwork(b.Byte(4))\n\t\tb.Advance(5)\n\n\t\taddr, port, err := addrParser.ReadAddressPort(nil, b)\n\t\tif err != nil {\n\t\t\treturn errors.New(\"failed to parse address and port\").Base(err)\n\t\t}\n\n\t\tswitch network {\n\t\tcase TargetNetworkTCP:\n\t\t\tf.Target = net.TCPDestination(addr, port)\n\t\tcase TargetNetworkUDP:\n\t\t\tf.Target = net.UDPDestination(addr, port)\n\t\tdefault:\n\t\t\treturn errors.New(\"unknown network type: \", network)\n\t\t}\n\t}\n\n\tif f.SessionStatus == SessionStatusNew && readSourceAndLocal {\n\t\tf.Inbound = &session.Inbound{}\n\n\t\tif b.Len() == 0 {\n\t\t\treturn nil // for heartbeat, etc.\n\t\t}","sourceCodeStart":136,"sourceCodeEnd":172,"githubUrl":"https://github.com/XTLS/Xray-core/blob/7d214f8b094f75322fa3990f8aadad1c912f24f5/common/mux/frame.go#L136-L172","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify both endpoints run the same (latest) Xray-core version so frame encoding matches.","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).","Disable Mux temporarily on the outbound to confirm the connection itself is healthy; if it works, the problem is frame encoding, not transport.","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.","Capture the stream and inspect the frame at the failure offset to see whether the payload is mux metadata or unrelated data."],"exampleFix":"// client config (JSON): make sure mux is only enabled when the server supports it\n// before\n\"outbounds\": [{ \"protocol\": \"vless\", \"settings\": {}, \"streamSettings\": { \"mux\": { \"enabled\": true } } }]\n// after: same version on both sides and correct address encoding\n\"outbounds\": [{ \"protocol\": \"vless\", \"settings\": {}, \"streamSettings\": { \"mux\": { \"enabled\": true, \"concurrency\": 8 } } }]","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"// In Go, treat frame parse errors as fatal for the mux connection:\nif err := meta.Unmarshal(reader, isReverse); err != nil {\n    // close the whole mux connection; do not retry parsing the same stream\n    cancel()\n    log.Warn(\"mux frame unmarshal failed, closing connection: \", err)\n}","preventionTips":["Pin identical Xray-core versions on client and server.","Only enable mux on outbounds whose server side actually speaks the same mux protocol.","When testing custom mux encoders, fuzz RoundTrip(Unmarshal(x)) against your encoder before deploying."],"tags":["mux","protocol","parsing","xray"],"backgroundTag":null,"analyzedSha":"7d214f8b094f75322fa3990f8aadad1c912f24f5","analyzedAt":"2026-08-15T14:26:24.325Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}