{"record":{"id":"b308ccd7b311fbb9","repo":"XTLS/Xray-core","slug":"failed-to-dispatch-request","errorCode":null,"errorMessage":"failed to dispatch request.","messagePattern":"failed to dispatch request\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"common/mux/server.go","lineNumber":269,"sourceCode":"\t\t\tID:           meta.SessionID,\n\t\t\ttransferType: protocol.TransferTypePacket,\n\t\t\tXUDP:         x,\n\t\t}\n\t\tx.Status = Active\n\t\tif !w.sessionManager.Add(x.Mux) {\n\t\t\tx.Mux.Close(false)\n\t\t\treturn errors.New(\"failed to add new session\")\n\t\t}\n\t\tgo handle(ctx, x.Mux, w.link.Writer)\n\t\treturn nil\n\t}\n\n\tlink, err := w.dispatcher.Dispatch(ctx, meta.Target)\n\tif err != nil {\n\t\tif meta.Option.Has(OptionData) {\n\t\t\tbuf.Copy(NewStreamReader(reader), buf.Discard)\n\t\t}\n\t\treturn errors.New(\"failed to dispatch request.\").Base(err)\n\t}\n\ts := &Session{\n\t\tinput:        link.Reader,\n\t\toutput:       link.Writer,\n\t\tparent:       w.sessionManager,\n\t\tID:           meta.SessionID,\n\t\ttransferType: protocol.TransferTypeStream,\n\t}\n\tif meta.Target.Network == net.Network_UDP {\n\t\ts.transferType = protocol.TransferTypePacket\n\t}\n\tif !w.sessionManager.Add(s) {\n\t\ts.Close(false)\n\t\treturn errors.New(\"failed to add new session\")\n\t}\n\tgo handle(ctx, s, w.link.Writer)\n\tif !meta.Option.Has(OptionData) {\n\t\treturn nil","sourceCodeStart":251,"sourceCodeEnd":287,"githubUrl":"https://github.com/XTLS/Xray-core/blob/7d214f8b094f75322fa3990f8aadad1c912f24f5/common/mux/server.go#L251-L287","documentation":"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.","triggerScenarios":"Target destination cannot be routed/dispatched: no matching outbound, routing rule rejection (blocked domain/IP), invalid destination, or dispatcher-level policy failure.","commonSituations":"Routing rules blocking a multiplexed domain, missing/removed outbound referenced by rules, balancer with all failed outbounds, or DNS/resolution failures for the target.","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."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"link, err := dispatcher.Dispatch(ctx, target)\nif err != nil {\n    // per-request error handling belongs here (pre-mux); once inside mux the connection is doomed\n    return fmt.Errorf(\"dispatch %v failed: %w\", target, err)\n}","preventionTips":["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."],"tags":["mux","dispatch","routing","xray"],"backgroundTag":null,"analyzedSha":"7d214f8b094f75322fa3990f8aadad1c912f24f5","analyzedAt":"2026-08-15T14:26:24.325Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}