{"record":{"id":"7c8d53ecdeb0d5aa","repo":"XTLS/Xray-core","slug":"failed-to-process-mux-outbound-traffic","errorCode":null,"errorMessage":"failed to process mux outbound traffic","messagePattern":"failed to process mux outbound traffic","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"app/proxyman/outbound/handler.go","lineNumber":214,"sourceCode":"\t\t\t\tcommon.Interrupt(link.Writer)\n\t\t\t\tcommon.Interrupt(link.Reader)\n\t\t\t\treturn\n\t\t\t}\n\n\t\t} else {\n\t\t\tunchangedDomain := ob.Target.Address.Domain()\n\t\t\tob.Target.Address = net.IPAddress(ips[dice.Roll(len(ips))])\n\t\t\terrors.LogInfo(ctx, \"target: \", unchangedDomain, \" resolved to: \", ob.Target.Address.String())\n\t\t}\n\t}\n\tif ob.Target.Network == net.Network_UDP && ob.OriginalTarget.Address != nil && ob.OriginalTarget.Address != ob.Target.Address {\n\t\tlink.Reader = &buf.EndpointOverrideReader{Reader: link.Reader, Dest: ob.Target.Address, OriginalDest: ob.OriginalTarget.Address}\n\t\tlink.Writer = &buf.EndpointOverrideWriter{Writer: link.Writer, Dest: ob.Target.Address, OriginalDest: ob.OriginalTarget.Address}\n\t}\n\tif h.mux != nil {\n\t\ttest := func(err error) {\n\t\t\tif err != nil {\n\t\t\t\terr := errors.New(\"failed to process mux outbound traffic\").Base(err)\n\t\t\t\tsession.SubmitOutboundErrorToOriginator(ctx, err)\n\t\t\t\terrors.LogInfo(ctx, err.Error())\n\t\t\t\tcommon.Interrupt(link.Writer)\n\t\t\t\tcommon.Interrupt(link.Reader)\n\t\t\t}\n\t\t}\n\t\tif ob.Target.Network == net.Network_UDP && ob.Target.Port == 443 {\n\t\t\tswitch h.udp443 {\n\t\t\tcase \"reject\":\n\t\t\t\ttest(errors.New(\"XUDP rejected UDP/443 traffic\").AtInfo())\n\t\t\t\treturn\n\t\t\tcase \"skip\":\n\t\t\t\tgoto out\n\t\t\t}\n\t\t}\n\t\tif h.xudp != nil && ob.Target.Network == net.Network_UDP {\n\t\t\tif !h.xudp.Enabled {\n\t\t\t\tgoto out","sourceCodeStart":196,"sourceCodeEnd":232,"githubUrl":"https://github.com/XTLS/Xray-core/blob/7d214f8b094f75322fa3990f8aadad1c912f24f5/app/proxyman/outbound/handler.go#L196-L232","documentation":"Wrapped error produced by the test() closure in the outbound handler whenever mux-related processing of a dispatched connection fails. It is the outer envelope for XUDP dispatch errors, UDP/443 policy rejections, and mux worker failures; the inner error (via .Base) carries the actual cause. On failure the error is submitted to the session originator, logged at info level, and both directions of the link are interrupted.","triggerScenarios":"Any of: h.xudp.Dispatch(ctx, link) returning an error for a UDP connection when xudp is configured; the UDP/443 reject path (see error 82); or other mux-path failures inside the h.mux != nil branch of the dispatch flow. The closure fires only when h.mux is configured on the handler.","commonSituations":"A XUDP/mux-capable outbound where the mux layer fails to initialize or carry the stream: broken mux cushion settings, a server that does not support XUDP/mux (inner error like unsupported or protocol failure), or UDP over mux with the peer closing the session. Frequently surfaces with 'XUDP rejected UDP/443 traffic' as the inner error when udp443:'reject' is set.","solutions":["Read the inner error in the log line: the Base() cause (XUDP reject, mux protocol error, connection closed) determines the real fix.","If the inner error is the UDP/443 rejection, set udp443 to 'skip' (or omit reject) or block QUIC at the client so UDP/443 is not offered.","If the inner error is a mux protocol failure, verify the remote server supports the configured mux (XUDP / mux.cool) and matching settings, or disable mux for that outbound.","Update to a current build; older mux/XUDP interop bugs between client and server produce spurious failures here."],"exampleFix":"// before\n\"streamSettings\": { \"udp443\": \"reject\" } // QUIC flows get killed under the mux error envelope\n\n// after\n\"streamSettings\": {} // omit udp443, or \"skip\", letting UDP/443 bypass mux instead of erroring","handlingStrategy":"try-catch","validationCode":"// Skip mux for traffic you know the mux path rejects\nif ob.Target.Network == net.Network_UDP && ob.Target.Port == 443 && handler.UDP443Policy() == \"reject\" {\n    return dispatchDirect(ctx, link) // avoid entering the mux branch\n}","typeGuard":null,"tryCatchPattern":"// Unwrap: the real cause is under the envelope via errors.Unwrap\nif err := handler.Dispatch(ctx, link); err != nil {\n    if strings.Contains(err.Error(), \"failed to process mux outbound traffic\") {\n        cause := errors.Unwrap(err) // XUDP reject, mux protocol error, etc.\n        log.Printf(\"mux path failed: %v\", cause)\n        if isTransient(cause) { return retry(ctx, link) }\n    }\n    return err\n}","preventionTips":["Keep mux/XUDP settings identical on client and server","Pin a udp443 policy ('skip') instead of relying on defaults when QUIC must pass","Version-lock core on both ends when using mux features","Log and count these envelopes; a spike usually means transport-layer breakage, not code bugs"],"tags":["go","xray","mux","xudp","outbound"],"backgroundTag":null,"analyzedSha":"7d214f8b094f75322fa3990f8aadad1c912f24f5","analyzedAt":"2026-08-15T14:26:24.325Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}