{"record":{"id":"a5a0e140cbcac2b8","repo":"XTLS/Xray-core","slug":"failed-to-add-new-session","errorCode":null,"errorMessage":"failed to add new session","messagePattern":"failed to add new session","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"common/mux/server.go","lineNumber":258,"sourceCode":"\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\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,","sourceCodeStart":240,"sourceCodeEnd":276,"githubUrl":"https://github.com/XTLS/Xray-core/blob/7d214f8b094f75322fa3990f8aadad1c912f24f5/common/mux/server.go#L240-L276","documentation":"sessionManager.Add returned false for a freshly created XUDP session, meaning the session could not be registered (the manager tracks sessions by ID and refuses inconsistent states, typically a duplicate or otherwise unaddable SessionID). The session is closed and the error returned, terminating the Mux connection.","triggerScenarios":"An XUDP SessionStatusNew/reattach path where the SessionID is already present in the manager or the manager is in a state that refuses the add; often follows unusual frame orderings (Keep before New, duplicated New).","commonSituations":"Client bugs that reuse SessionIDs across XUDP reattach attempts, or races between the XUDP takeover path and normal session registration.","solutions":["Check earlier log lines for a duplicate SessionID or frame-order anomaly on the same mux connection.","Upgrade both endpoints to the latest Xray-core; XUDP session-registration races have been fixed over time.","In custom clients, guarantee unique SessionIDs per substream and send New before Keep for each ID.","If reproducible, capture the frame sequence and report it upstream."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// Custom clients: ensure SessionID uniqueness before sending New:\nif _, exists := usedIDs[id]; exists {\n    return fmt.Errorf(\"session id %d already in use\", id)\n}","typeGuard":null,"tryCatchPattern":"if err := worker.handleFrame(ctx, reader); err != nil {\n    if strings.Contains(err.Error(), \"failed to add new session\") {\n        // connection is dead by design; client should open a new mux connection, not resend on this one\n    }\n}","preventionTips":["Never reuse SessionIDs within one mux connection.","Send End before abandoning a substream so the server frees the ID.","Stay current with Xray-core releases for XUDP registration fixes."],"tags":["mux","xudp","session","xray"],"backgroundTag":null,"analyzedSha":"7d214f8b094f75322fa3990f8aadad1c912f24f5","analyzedAt":"2026-08-15T14:26:24.325Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}