XTLS/Xray-core · error

failed to add new session

Error message

failed to add new session

What it means

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.

Source

Thrown at common/mux/server.go:258

			link.Writer.WriteMultiBuffer(mb) // it's meaningless to test a new pipe
			x.Mux = &Session{
				input:  link.Reader,
				output: link.Writer,
			}
			errors.LogInfoInner(ctx, err, "XUDP new ", meta.GlobalID)
		}
		x.Mux = &Session{
			input:        x.Mux.input,
			output:       x.Mux.output,
			parent:       w.sessionManager,
			ID:           meta.SessionID,
			transferType: protocol.TransferTypePacket,
			XUDP:         x,
		}
		x.Status = Active
		if !w.sessionManager.Add(x.Mux) {
			x.Mux.Close(false)
			return errors.New("failed to add new session")
		}
		go handle(ctx, x.Mux, w.link.Writer)
		return nil
	}

	link, err := w.dispatcher.Dispatch(ctx, meta.Target)
	if err != nil {
		if meta.Option.Has(OptionData) {
			buf.Copy(NewStreamReader(reader), buf.Discard)
		}
		return errors.New("failed to dispatch request.").Base(err)
	}
	s := &Session{
		input:        link.Reader,
		output:       link.Writer,
		parent:       w.sessionManager,
		ID:           meta.SessionID,
		transferType: protocol.TransferTypeStream,

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Check earlier log lines for a duplicate SessionID or frame-order anomaly on the same mux connection.
2. Upgrade both endpoints to the latest Xray-core; XUDP session-registration races have been fixed over time.
3. In custom clients, guarantee unique SessionIDs per substream and send New before Keep for each ID.
4. If reproducible, capture the frame sequence and report it upstream.

// Custom clients: ensure SessionID uniqueness before sending New:
if _, exists := usedIDs[id]; exists {
    return fmt.Errorf("session id %d already in use", id)
}

if err := worker.handleFrame(ctx, reader); err != nil {
    if strings.Contains(err.Error(), "failed to add new session") {
        // connection is dead by design; client should open a new mux connection, not resend on this one
    }
}

When it happens

Trigger: 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).

Common situations: Client bugs that reuse SessionIDs across XUDP reattach attempts, or races between the XUDP takeover path and normal session registration.

Related errors

• failed to process mux outbound traffic
• packet size too large:
• conflict
• XUDP new
• XUDP rejected UDP/443 traffic

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