XTLS/Xray-core · error

failed to dispatch request

Error message

failed to dispatch request

What it means

Thrown by the SOCKS inbound when dispatcher.DispatchLink fails while establishing the outbound tunnel for an accepted TCP request. The Base error carries the routing/dispatch failure — typically no matching outbound, all outbounds failing, or the destination rejected by policy.

Source

Thrown at proxy/socks/server.go:163

		errors.LogInfo(ctx, "TCP Connect request to ", dest)
		if inbound.Source.IsValid() {
			ctx = log.ContextWithAccessMessage(ctx, &log.AccessMessage{
				From:   inbound.Source,
				To:     dest,
				Status: log.AccessAccepted,
				Reason: "",
			})
		}
		if inbound.CanSpliceCopy == 2 {
			inbound.CanSpliceCopy = 1
		}
		if err := dispatcher.DispatchLink(
			ctx, dest, &transport.Link{
				Reader: reader,
				Writer: buf.NewWriter(conn),
			},
		); err != nil {
			return errors.New("failed to dispatch request").Base(err)
		}
		return nil
	}

	if request.Command == protocol.RequestCommandUDP {
		if tempUDPConn == nil {
			return errors.New("UDP associate with listen port failed")
		}
		tempUDPConn.SetTimeout(plcy.Timeouts.ConnectionIdle)
		errCh := make(chan error, 1)
		go func() {
			errCh <- s.handleUDPPayload(ctx, tempUDPConn, dispatcher)
		}()
		// Associated TCP keeps the UDP alive
		// Close UDP if TCP connection is closed
		// Or Close TCP if UDP is idle timeout
		io.Copy(buf.DiscardBytes, conn)
		tempUDPConn.Close()

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Read the Base error — it names the outbound and underlying dial failure.
2. Test routing for the failing destination with Xray's routing log or api RouterService to see which outbound is chosen.
3. Fix or restart the target outbound (check its address, TLS settings, and network reachability).
4. Add a fallback outbound (blackhole/freedom) so unmatched traffic gets a defined result.

if err := dispatcher.DispatchLink(ctx, dest, link); err != nil {
	if strings.Contains(err.Error(), "failed to dispatch request") {
		// inspect base error; optionally retry once or fall to a backup outbound
	}
}

When it happens

Trigger: After a successful SOCKS handshake for RequestCommandTCP, dispatcher.DispatchLink(ctx, dest, link) returns non-nil: e.g. routing sends to an outbound whose server is unreachable, the balancer has no healthy candidates, or the target is blocked by rule action reject.

Common situations: Routing rules directing traffic to a dead/freedom-blocked outbound; balancer cluster fully down; 'reject' rule matching the destination; outbound server credentials or SNI broken so every dial fails.

Related errors

• XUDP new
• failed to dispatch request.
• SOCKS settings: "servers" should have one and only one membe
• SOCKS servers: "users" should have one member at most. Multi
• failed to read from connection

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