What causes "failed to dispatch request." in XTLS/Xray-core?

Inspect the Base() error in logs to find the real dispatch reason.

failed to dispatch request.

Error message

failed to dispatch request.

What it means

The dispatcher rejected a normal (non-XUDP) mux SessionStatusNew request: Dispatch(ctx, meta.Target) failed before a session was even created. The raw dispatch failure is wrapped as 'failed to dispatch request.' and, since mux shares one connection, this error tears down the whole Mux connection.

Source

Thrown at common/mux/server.go:269

			ID:           meta.SessionID,
			transferType: protocol.TransferTypePacket,
			XUDP:         x,
		}
		x.Status = Active
		if !w.sessionManager.Add(x.Mux) {
			x.Mux.Close(false)
			return errors.New("failed to add new session")
		}
		go handle(ctx, x.Mux, w.link.Writer)
		return nil
	}

	link, err := w.dispatcher.Dispatch(ctx, meta.Target)
	if err != nil {
		if meta.Option.Has(OptionData) {
			buf.Copy(NewStreamReader(reader), buf.Discard)
		}
		return errors.New("failed to dispatch request.").Base(err)
	}
	s := &Session{
		input:        link.Reader,
		output:       link.Writer,
		parent:       w.sessionManager,
		ID:           meta.SessionID,
		transferType: protocol.TransferTypeStream,
	}
	if meta.Target.Network == net.Network_UDP {
		s.transferType = protocol.TransferTypePacket
	}
	if !w.sessionManager.Add(s) {
		s.Close(false)
		return errors.New("failed to add new session")
	}
	go handle(ctx, s, w.link.Writer)
	if !meta.Option.Has(OptionData) {
		return nil

View on GitHub (pinned to 7d214f8b09)

Solutions

Inspect the Base() error in logs to find the real dispatch reason.
Verify routing config: make sure the destination falls into a valid outbound and is not blocked by a reject rule unintentionally.
Confirm a working default outbound exists.
Retest the same target with mux disabled to verify the non-mux path dispatches fine, isolating whether the target itself is the problem.

Defensive patterns

Strategy: try-catch

Try / catch

link, err := dispatcher.Dispatch(ctx, target)
if err != nil {
    // per-request error handling belongs here (pre-mux); once inside mux the connection is doomed
    return fmt.Errorf("dispatch %v failed: %w", target, err)
}

Prevention

Guarantee a valid default outbound for any destination the client may mux.
Audit reject/block routing rules against the destinations actually used.
Prefer dispatching fragile/unusual destinations outside mux so one failure cannot kill the connection.

When it happens

Trigger: Target destination cannot be routed/dispatched: no matching outbound, routing rule rejection (blocked domain/IP), invalid destination, or dispatcher-level policy failure.

Common situations: Routing rules blocking a multiplexed domain, missing/removed outbound referenced by rules, balancer with all failed outbounds, or DNS/resolution failures for the target.

Related errors

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