XTLS/Xray-core · error

write boolean: %w

Error message

write boolean: %w

What it means

Boolean.writeTo writes a single 0/1 byte to the underlying io.Writer and wraps any failure from that Write with this message. The error itself is always an I/O problem (closed connection, broken pipe, buffer/full write error) — the boolean encoding itself cannot fail.

Source

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

func (v *Boolean) readFrom(r io.Reader) error {
	b, err := readByte(r)
	if err != nil {
		return fmt.Errorf("read boolean: %w", err)
	}
	if b > 1 {
		return fmt.Errorf("read boolean: invalid value: %d", b)
	}
	*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 {

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Inspect the wrapped error (%w) — ErrConnClosed/broken pipe means the peer went away; treat as connection loss, not a bug.
2. Ensure only one goroutine writes to the connection at a time (the transport serializes writes; don't bypass it).
3. Add write deadlines so a stalled peer surfaces as a timeout instead of an indefinite block followed by RST.
4. If it happens immediately on connect, check for protocol/port mismatch hitting a non-Minecraft service.

if err := boolField.writeTo(w); err != nil {
    if errors.Is(err, net.ErrClosed) || isBrokenPipe(err) {
        // peer gone: abandon connection
        return err
    }
    var nerr net.Error
    if errors.As(err, &nerr) && nerr.Timeout() {
        return fmt.Errorf("write stalled: %w", err)
    }
    return err
}

When it happens

Trigger: Encoding a Minecraft protocol packet containing a Boolean field after the peer has disconnected or the connection entered an error state; writing to a bytes.Buffer that is backed by a full/closed resource.

Common situations: Server closes the socket mid-handshake (timeout, ban, restart); NAT/firewall drops the TCP connection; concurrent write on the same conn from two goroutines causing one side to see a closed writer.

Related errors

• write UUID: %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/bee5b42a45542cbb. Report an issue: GitHub.