XTLS/Xray-core · error

failed to process data

Error message

failed to process data

What it means

A status handler (handleStatusKeepAlive/End/New/Keep) returned an error, and handleFrame wraps it as 'failed to process data'. This is a pass-through wrapper: the Base() error (dispatch failure, session-add failure, unexpected network, packet read error, etc.) carries the real cause, and the error ends the mux connection's run loop.

Source

Thrown at common/mux/server.go:358

		return errors.New("failed to read metadata").Base(err)
	}

	switch meta.SessionStatus {
	case SessionStatusKeepAlive:
		err = w.handleStatusKeepAlive(&meta, reader)
	case SessionStatusEnd:
		err = w.handleStatusEnd(&meta, reader)
	case SessionStatusNew:
		err = w.handleStatusNew(session.ContextWithIsReverseMux(ctx, false), &meta, reader)
	case SessionStatusKeep:
		err = w.handleStatusKeep(&meta, reader)
	default:
		status := meta.SessionStatus
		return errors.New("unknown status: ", status).AtError()
	}

	if err != nil {
		return errors.New("failed to process data").Base(err)
	}
	return nil
}

func (w *ServerWorker) run(ctx context.Context) {
	defer func() {
		common.Must(w.done.Close())
	}()

	reader := &buf.BufferedReader{Reader: w.link.Reader}

	for {
		select {
		case <-ctx.Done():
			return
		default:
			err := w.handleFrame(ctx, reader)
			if err != nil {

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Always read the full error chain (LogError prints Base()) and fix the underlying handler error (see errors 167-172, 166).
2. Enable access/routing logs at debug level to capture which substream/status triggered the failure.
3. Once the base cause is fixed, this error disappears; the wrapper itself needs no separate remedy.
4. If the base error is a transient upstream failure, note that mux shares fate: one bad substream request can drop the whole connection, so validate destinations before muxing them.

if err := w.handleFrame(ctx, reader); err != nil {
    // 'failed to process data' is a wrapper; always inspect the base error
    cause := err
    for errors.Unwrap(cause) != nil { cause = errors.Unwrap(cause) }
    log.Warn("mux handler failed, root cause: ", cause)
    return err // run loop exits, mux connection closes
}

When it happens

Trigger: Any of the per-status handlers failing: dispatch rejection (171/169), session add collision (172/170), network restriction (167), or data-frame read errors.

Common situations: Developers see only this message in logs and chase the wrapper; the actionable detail is always in the chained base error logged alongside it.

Related errors

• failed to process mux outbound traffic
• XUDP rejected UDP/443 traffic
• failed to create mux client worker
• failed to create portal worker
• empty worker list

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