XTLS/Xray-core · warning

read minecraft custom payload data: %w

Error message

read minecraft custom payload data: %w

What it means

parseCustomPayload failed to read the payload bytes after the channel String with io.ReadFull. Because the reader is an in-memory bytes.Reader over the already-received packet data and the slice is sized to r.Len(), this error is effectively unreachable; hitting it indicates an internal bug in packet handling rather than a network problem.

Source

Thrown at transport/internet/finalmask/xmc/packet_stream.go:156

func (s *packetStream) remoteCustomPayloadID() int {
	if s.isClient {
		return configurationClientboundCustomPayload
	}
	return configurationServerboundCustomPayload
}

func parseCustomPayload(packet *mcPacket) ([]byte, bool, error) {
	r := bytes.NewReader(packet.data)
	var channel String
	if err := channel.readFrom(r); err != nil {
		return nil, false, fmt.Errorf("read minecraft custom payload channel: %w", err)
	}
	if string(channel) != packetChannel {
		return nil, false, nil
	}
	payload := make([]byte, r.Len())
	if _, err := io.ReadFull(r, payload); err != nil {
		return nil, false, fmt.Errorf("read minecraft custom payload data: %w", err)
	}
	return payload, true, nil
}

func (s *packetStream) writeKeepAlive(id Long) error {
	s.writeMu.Lock()
	defer s.writeMu.Unlock()
	if err := writePacket(s.writer, configurationKeepAlive, &id); err != nil {
		return fmt.Errorf("write minecraft keep-alive: %w", err)
	}
	return nil
}

func (s *packetStream) keepAliveLoop() {
	ticker := time.NewTicker(keepAlivePeriod)
	defer ticker.Stop()
	for {
		select {

View on GitHub (pinned to 7d214f8b09)

Solutions

1. If maintaining a fork, verify packet.data passed to parseCustomPayload is the complete undecoded body
2. Report upstream with a packet hex dump if it reproduces on unmodified code
3. No runtime workaround exists; the error is defensive

n, err := stream.Read(buf)
if err != nil && strings.Contains(err.Error(), "custom payload data") {
    // internal invariant: report with full context and close
    return fmt.Errorf("xmc internal decode bug: %w", err)
}

When it happens

Trigger: A custom-payload packet on channel "xmc:data" whose trailing byte count does not match expectations due to a bug in readPacket/mcPacket handling, or a fork that changed how packet.data is populated.

Common situations: Patches to mcPacket that truncate packet.data; custom builds altering parseCustomPayload; not observed in stock code paths.

Related errors

• read minecraft keep-alive: %w
• read minecraft custom payload channel: %w
• outbound metadata not found
• new crypto reader: %w
• new crypto writer: %w

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