{"record":{"id":"49c3bb96527d4c43","repo":"XTLS/Xray-core","slug":"failed-to-dispatch-request-49c3bb","errorCode":null,"errorMessage":"failed to dispatch request","messagePattern":"failed to dispatch request","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"proxy/socks/server.go","lineNumber":163,"sourceCode":"\t\terrors.LogInfo(ctx, \"TCP Connect request to \", dest)\n\t\tif inbound.Source.IsValid() {\n\t\t\tctx = log.ContextWithAccessMessage(ctx, &log.AccessMessage{\n\t\t\t\tFrom:   inbound.Source,\n\t\t\t\tTo:     dest,\n\t\t\t\tStatus: log.AccessAccepted,\n\t\t\t\tReason: \"\",\n\t\t\t})\n\t\t}\n\t\tif inbound.CanSpliceCopy == 2 {\n\t\t\tinbound.CanSpliceCopy = 1\n\t\t}\n\t\tif err := dispatcher.DispatchLink(\n\t\t\tctx, dest, &transport.Link{\n\t\t\t\tReader: reader,\n\t\t\t\tWriter: buf.NewWriter(conn),\n\t\t\t},\n\t\t); err != nil {\n\t\t\treturn errors.New(\"failed to dispatch request\").Base(err)\n\t\t}\n\t\treturn nil\n\t}\n\n\tif request.Command == protocol.RequestCommandUDP {\n\t\tif tempUDPConn == nil {\n\t\t\treturn errors.New(\"UDP associate with listen port failed\")\n\t\t}\n\t\ttempUDPConn.SetTimeout(plcy.Timeouts.ConnectionIdle)\n\t\terrCh := make(chan error, 1)\n\t\tgo func() {\n\t\t\terrCh <- s.handleUDPPayload(ctx, tempUDPConn, dispatcher)\n\t\t}()\n\t\t// Associated TCP keeps the UDP alive\n\t\t// Close UDP if TCP connection is closed\n\t\t// Or Close TCP if UDP is idle timeout\n\t\tio.Copy(buf.DiscardBytes, conn)\n\t\ttempUDPConn.Close()","sourceCodeStart":145,"sourceCodeEnd":181,"githubUrl":"https://github.com/XTLS/Xray-core/blob/7d214f8b094f75322fa3990f8aadad1c912f24f5/proxy/socks/server.go#L145-L181","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the Base error — it names the outbound and underlying dial failure.","Test routing for the failing destination with Xray's routing log or api RouterService to see which outbound is chosen.","Fix or restart the target outbound (check its address, TLS settings, and network reachability).","Add a fallback outbound (blackhole/freedom) so unmatched traffic gets a defined result."],"exampleFix":null,"handlingStrategy":"fallback","validationCode":null,"typeGuard":null,"tryCatchPattern":"if err := dispatcher.DispatchLink(ctx, dest, link); err != nil {\n\tif strings.Contains(err.Error(), \"failed to dispatch request\") {\n\t\t// inspect base error; optionally retry once or fall to a backup outbound\n\t}\n}","preventionTips":["Configure a freedom/blackhole fallback outbound in routing.","Health-check outbounds (balancer strategy) so dispatch never lands on a dead one.","Alert on dispatch failure rate, not just connection errors."],"tags":["socks","inbound","dispatch","routing","outbound"],"backgroundTag":null,"analyzedSha":"7d214f8b094f75322fa3990f8aadad1c912f24f5","analyzedAt":"2026-08-15T14:26:24.325Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}