XTLS/Xray-core · error

failed to process mux outbound traffic

Error message

failed to process mux outbound traffic

What it means

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.

Source

Thrown at app/proxyman/outbound/handler.go:214

				common.Interrupt(link.Writer)
				common.Interrupt(link.Reader)
				return
			}

		} else {
			unchangedDomain := ob.Target.Address.Domain()
			ob.Target.Address = net.IPAddress(ips[dice.Roll(len(ips))])
			errors.LogInfo(ctx, "target: ", unchangedDomain, " resolved to: ", ob.Target.Address.String())
		}
	}
	if ob.Target.Network == net.Network_UDP && ob.OriginalTarget.Address != nil && ob.OriginalTarget.Address != ob.Target.Address {
		link.Reader = &buf.EndpointOverrideReader{Reader: link.Reader, Dest: ob.Target.Address, OriginalDest: ob.OriginalTarget.Address}
		link.Writer = &buf.EndpointOverrideWriter{Writer: link.Writer, Dest: ob.Target.Address, OriginalDest: ob.OriginalTarget.Address}
	}
	if h.mux != nil {
		test := func(err error) {
			if err != nil {
				err := errors.New("failed to process mux outbound traffic").Base(err)
				session.SubmitOutboundErrorToOriginator(ctx, err)
				errors.LogInfo(ctx, err.Error())
				common.Interrupt(link.Writer)
				common.Interrupt(link.Reader)
			}
		}
		if ob.Target.Network == net.Network_UDP && ob.Target.Port == 443 {
			switch h.udp443 {
			case "reject":
				test(errors.New("XUDP rejected UDP/443 traffic").AtInfo())
				return
			case "skip":
				goto out
			}
		}
		if h.xudp != nil && ob.Target.Network == net.Network_UDP {
			if !h.xudp.Enabled {
				goto out

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Read the inner error in the log line: the Base() cause (XUDP reject, mux protocol error, connection closed) determines the real fix.
2. 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.
3. 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.
4. Update to a current build; older mux/XUDP interop bugs between client and server produce spurious failures here.

Example fix

// before
"streamSettings": { "udp443": "reject" } // QUIC flows get killed under the mux error envelope

// after
"streamSettings": {} // omit udp443, or "skip", letting UDP/443 bypass mux instead of erroring

// Skip mux for traffic you know the mux path rejects
if ob.Target.Network == net.Network_UDP && ob.Target.Port == 443 && handler.UDP443Policy() == "reject" {
    return dispatchDirect(ctx, link) // avoid entering the mux branch
}

// Unwrap: the real cause is under the envelope via errors.Unwrap
if err := handler.Dispatch(ctx, link); err != nil {
    if strings.Contains(err.Error(), "failed to process mux outbound traffic") {
        cause := errors.Unwrap(err) // XUDP reject, mux protocol error, etc.
        log.Printf("mux path failed: %v", cause)
        if isTransient(cause) { return retry(ctx, link) }
    }
    return err
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• cannot dial remote address
• cannot finish connection
• failed to resolve ip for target ${domain}
• XUDP rejected UDP/443 traffic
• failed to process outbound traffic

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