XTLS/Xray-core · error

write packet field: %w

Error message

write packet field: %w

What it means

Returned by encodePacket when a single field's writeTo fails while serializing fields into an in-memory bytes.Buffer prior to framing. Because bytes.Buffer writes never return errors, this path is only reachable if a field type implements writeTo with its own failure logic. In practice it is a defensive guard inside the Minecraft packet encoder used by the xmc transport.

Source

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

func writePacketWithLength(w io.Writer, packetID int, fields ...field) (int, error) {
	frame, err := encodePacket(packetID, fields...)
	if err != nil {
		return 0, err
	}
	if err = writeFull(w, frame); err != nil {
		return 0, fmt.Errorf("write packet data: %w", err)
	}
	return len(frame), nil
}

func encodePacket(packetID int, fields ...field) ([]byte, error) {
	var dataBuf bytes.Buffer

	for _, field := range fields {
		err := field.writeTo(&dataBuf)
		if err != nil {
			return nil, fmt.Errorf("write packet field: %w", err)
		}
	}
	if dataBuf.Len() > maxPacketDataLength {
		return nil, fmt.Errorf("write packet: bad length: %d", dataBuf.Len())
	}

	packetIDVarint := Varint(packetID)
	bodyLength := varintSize(packetIDVarint) + dataBuf.Len()
	if bodyLength > maxPacketBodyLength {
		return nil, fmt.Errorf("write packet: bad length: %d", bodyLength)
	}

	var frame bytes.Buffer
	frame.Grow(varintSize(Varint(bodyLength)) + bodyLength)
	frameLength := Varint(bodyLength)
	if err := frameLength.writeTo(&frame); err != nil {
		return nil, fmt.Errorf("write packet length: %w", err)
	}

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Inspect the wrapped error (%w) to identify which field type failed to serialize
2. Verify you are not passing a custom field implementation with a fallible writeTo
3. If unreachable in your code path, treat as an internal invariant violation and report upstream

if _, err := writePacket(w, id, fields...); err != nil {\n\tif strings.Contains(err.Error(), "write packet field") {\n\t\t// serialization invariant failure: inspect err via errors.Unwrap\n\t\tlog.Debug("xmc: field serialization failed: ", err)\n\t}\n\treturn err\n}

When it happens

Trigger: Calling writePacket/encodePacket with any field whose writeTo returns an error during serialization into the dataBuf bytes.Buffer in transport/internet/finalmask/xmc/protocol.go:400.

Common situations: Almost never seen in production; would only surface from a custom field type or future codec changes introducing fallible writes. Encountered mainly in tests that inject failing field implementations.

Related errors

• write packet length: %w
• write packet ID: %w
• write packet: bad length: %d
• set deadline: %w
• not a Service.

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