XTLS/Xray-core · error

unknown status:

Error message

unknown status: 

What it means

FrameMetadata.Unmarshal succeeded but the decoded SessionStatus is none of KeepAlive(0), End(1), New(2), Keep(3). The frame's status byte holds an undefined value, so the server cannot route it to a handler and returns the error marked AtError, breaking the mux connection.

Source

Thrown at common/mux/server.go:354

func (w *ServerWorker) handleFrame(ctx context.Context, reader *buf.BufferedReader) error {
	var meta FrameMetadata
	err := meta.Unmarshal(reader, session.IsReverseMuxFromContext(ctx))
	if err != nil {
		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():

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Log the numeric status value: a stable value points to protocol mismatch; random values point to corruption/desync.
2. Upgrade both endpoints to the same Xray-core release.
3. Verify no extra protocol layer (e.g. SOCKS/HTTP bytes) is being piped into the mux reader.
4. Capture traffic and check the frame right before the failure for an earlier desync.

if err := worker.handleFrame(ctx, reader); err != nil {
    if strings.Contains(err.Error(), "unknown status") {
        // protocol mismatch or corruption: close and renegotiate versions
    }
}

When it happens

Trigger: Status byte >= 4 or otherwise invalid: corrupted stream, incompatible protocol implementation, or a stream that was never mux traffic but happened to decode a length+status pair.

Common situations: Protocol version drift (newer status values unknown to the old side), custom mux clients, or feeding arbitrary bytes into a mux inbound.

Related errors

• unknown network type:
• invalid metalen
• insufficient buffer:
• failed to parse address and port
• reading source: unknown network type:

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