XTLS/Xray-core · error

write UUID: %w

Error message

write UUID: %w

What it means

UUID.writeTo writes the fixed 16-byte UUID to the io.Writer and wraps any Write failure with this message. Like other 'write X: %w' errors in protocol.go, it is purely an I/O failure on the underlying connection or buffer, not a data problem.

Source

Thrown at transport/internet/finalmask/xmc/protocol.go:305

	*v = b == 1
	return nil
}

func (v *Boolean) writeTo(w io.Writer) error {
	value := byte(0)
	if *v {
		value = 1
	}
	if _, err := w.Write([]byte{value}); err != nil {
		return fmt.Errorf("write boolean: %w", err)
	}
	return nil
}

func (v *UUID) writeTo(w io.Writer) error {
	_, err := w.Write(v[:])
	if err != nil {
		return fmt.Errorf("write UUID: %w", err)
	}
	return nil
}

type Bytes []byte

func (v *Bytes) readFrom(r io.Reader) error {
	var length Varint
	err := length.readFrom(r)
	if err != nil {
		return fmt.Errorf("read bytes: %w", err)
	}

	if length < 0 || length >= 1024 {
		return fmt.Errorf("read bytes: invalid size: %d", length)
	}

	buf := make([]byte, length)

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Unwrap the error to distinguish connection-closed (peer gone) from timeout (deadline) and handle accordingly.
2. Retry the whole connection at a higher level if the transport policy allows.
3. Set sane write timeouts before the login exchange.
4. Verify the remote actually speaks this Minecraft-based protocol on that port.

err := uuidField.writeTo(w)
if err != nil {
    switch {
    case errors.Is(err, net.ErrClosed), isBrokenPipe(err):
        teardown(conn)
    case isNetTimeout(err):
        conn.SetWriteDeadline(time.Now().Add(biggerDeadline))
    }
}

When it happens

Trigger: Writing a handshake/login packet containing the profile UUID when the TCP connection is already closed, reset, or past its write deadline.

Common situations: Peer disconnects between the padding handshake and the login phase; mobile network switching dropping the socket; proxy chain (Xray routing) closing the outbound while the xmc layer is still encoding.

Related errors

• write boolean: %w
• read bytes: %w
• read remaining bytes: %w
• write remaining bytes: %w
• write bytes length: %w

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