XTLS/Xray-core · error

XUDP new

Error message

XUDP new 

What it means

While creating a new XUDP session, the dispatcher rejected Dispatch(ctx, meta.Target) (e.g. no matching outbound, blocked by routing rules, or invalid destination). The error wraps the underlying dispatch failure, the GlobalID entry is deleted from XUDPManager, and the error is returned with a comment noting it breaks the whole Mux connection.

Source

Thrown at common/mux/server.go:237

			b.UDP = mb[0].UDP
			if err = x.Mux.output.WriteMultiBuffer(mb); err != nil {
				x.Interrupt()
				mb = buf.MultiBuffer{b}
			} else {
				b.Release()
				mb = nil
			}
			errors.LogInfoInner(ctx, err, "XUDP hit ", meta.GlobalID)
		}
		if mb != nil {
			ctx = session.ContextWithTimeoutOnly(ctx, true)
			// Actually, it won't return an error in Xray-core's implementations.
			link, err := w.dispatcher.Dispatch(ctx, meta.Target)
			if err != nil {
				XUDPManager.Lock()
				delete(XUDPManager.Map, x.GlobalID)
				XUDPManager.Unlock()
				err = errors.New("XUDP new ", meta.GlobalID).Base(errors.New("failed to dispatch request to ", meta.Target).Base(err))
				return err // it will break the whole Mux connection
			}
			link.Writer.WriteMultiBuffer(mb) // it's meaningless to test a new pipe
			x.Mux = &Session{
				input:  link.Reader,
				output: link.Writer,
			}
			errors.LogInfoInner(ctx, err, "XUDP new ", meta.GlobalID)
		}
		x.Mux = &Session{
			input:        x.Mux.input,
			output:       x.Mux.output,
			parent:       w.sessionManager,
			ID:           meta.SessionID,
			transferType: protocol.TransferTypePacket,
			XUDP:         x,
		}
		x.Status = Active

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Read the wrapped base error ('failed to dispatch request to <target>') to identify the rejecting layer.
2. Check routing rules for the destination (rule logs show which rule matched) and adjust or add an outbound for it.
3. Ensure a default outbound (first outbound, or freedom) exists and is not marked as a balancer without candidates.
4. Test the same destination without mux/XUDP enabled to confirm it dispatches normally.

if err := w.handleStatusNew(ctx, &meta, reader); err != nil {
    if base := errors.Unwrap(err); base != nil && strings.Contains(base.Error(), "failed to dispatch") {
        // routing/outbound problem: log target, fix config; connection will close by design
    }
    return err
}

When it happens

Trigger: XUDP SessionStatusNew whose target cannot be dispatched: no outbound matches the destination address, routing rules block it, or the target address is invalid at the dispatch layer.

Common situations: Routing rules or an outbound blacklist that rejects the UDP destination multiplexed by the client; missing default outbound; balancer with no healthy candidates.

Related errors

• failed to dispatch request.
• failed to process mux outbound traffic
• packet size too large:
• unexpected network
• conflict

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