{"record":{"id":"c81dcff886486935","repo":"XTLS/Xray-core","slug":"xudp-new","errorCode":null,"errorMessage":"XUDP new ","messagePattern":"XUDP new ","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"common/mux/server.go","lineNumber":237,"sourceCode":"\t\t\tb.UDP = mb[0].UDP\n\t\t\tif err = x.Mux.output.WriteMultiBuffer(mb); err != nil {\n\t\t\t\tx.Interrupt()\n\t\t\t\tmb = buf.MultiBuffer{b}\n\t\t\t} else {\n\t\t\t\tb.Release()\n\t\t\t\tmb = nil\n\t\t\t}\n\t\t\terrors.LogInfoInner(ctx, err, \"XUDP hit \", meta.GlobalID)\n\t\t}\n\t\tif mb != nil {\n\t\t\tctx = session.ContextWithTimeoutOnly(ctx, true)\n\t\t\t// Actually, it won't return an error in Xray-core's implementations.\n\t\t\tlink, err := w.dispatcher.Dispatch(ctx, meta.Target)\n\t\t\tif err != nil {\n\t\t\t\tXUDPManager.Lock()\n\t\t\t\tdelete(XUDPManager.Map, x.GlobalID)\n\t\t\t\tXUDPManager.Unlock()\n\t\t\t\terr = errors.New(\"XUDP new \", meta.GlobalID).Base(errors.New(\"failed to dispatch request to \", meta.Target).Base(err))\n\t\t\t\treturn err // it will break the whole Mux connection\n\t\t\t}\n\t\t\tlink.Writer.WriteMultiBuffer(mb) // it's meaningless to test a new pipe\n\t\t\tx.Mux = &Session{\n\t\t\t\tinput:  link.Reader,\n\t\t\t\toutput: link.Writer,\n\t\t\t}\n\t\t\terrors.LogInfoInner(ctx, err, \"XUDP new \", meta.GlobalID)\n\t\t}\n\t\tx.Mux = &Session{\n\t\t\tinput:        x.Mux.input,\n\t\t\toutput:       x.Mux.output,\n\t\t\tparent:       w.sessionManager,\n\t\t\tID:           meta.SessionID,\n\t\t\ttransferType: protocol.TransferTypePacket,\n\t\t\tXUDP:         x,\n\t\t}\n\t\tx.Status = Active","sourceCodeStart":219,"sourceCodeEnd":255,"githubUrl":"https://github.com/XTLS/Xray-core/blob/7d214f8b094f75322fa3990f8aadad1c912f24f5/common/mux/server.go#L219-L255","documentation":"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.","triggerScenarios":"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.","commonSituations":"Routing rules or an outbound blacklist that rejects the UDP destination multiplexed by the client; missing default outbound; balancer with no healthy candidates.","solutions":["Read the wrapped base error ('failed to dispatch request to <target>') to identify the rejecting layer.","Check routing rules for the destination (rule logs show which rule matched) and adjust or add an outbound for it.","Ensure a default outbound (first outbound, or freedom) exists and is not marked as a balancer without candidates.","Test the same destination without mux/XUDP enabled to confirm it dispatches normally."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"if err := w.handleStatusNew(ctx, &meta, reader); err != nil {\n    if base := errors.Unwrap(err); base != nil && strings.Contains(base.Error(), \"failed to dispatch\") {\n        // routing/outbound problem: log target, fix config; connection will close by design\n    }\n    return err\n}","preventionTips":["Keep a healthy default outbound reachable for arbitrary XUDP targets.","Review routing rules for UDP destinations before enabling XUDP/mux.","Validate destinations client-side when possible to avoid mux fate-sharing."],"tags":["mux","xudp","dispatch","routing","xray"],"backgroundTag":null,"analyzedSha":"7d214f8b094f75322fa3990f8aadad1c912f24f5","analyzedAt":"2026-08-15T14:26:24.325Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}