XTLS/Xray-core · error

write minecraft custom payload: %w

Error message

write minecraft custom payload: %w

What it means

packetStream.Write failed while emitting a chunk of the tunnel payload as a Minecraft configuration custom-payload packet on channel "xmc:data" (max 24 KiB of data per packet). The wrapped error comes from writePacket and is almost always an underlying write failure on a broken or closed connection.

Source

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

func (s *packetStream) Write(p []byte) (int, error) {
	if len(p) == 0 {
		return 0, nil
	}

	s.writeMu.Lock()
	defer s.writeMu.Unlock()

	written := 0
	for written < len(p) {
		end := written + maxPacketData
		if end > len(p) {
			end = len(p)
		}
		channel := String(packetChannel)
		payload := RestBytes(p[written:end])
		if err := writePacket(s.writer, s.localCustomPayloadID(), &channel, &payload); err != nil {
			return written, fmt.Errorf("write minecraft custom payload: %w", err)
		}
		written = end
	}

	return written, nil
}

func (s *packetStream) Stop() {
	s.stopOnce.Do(func() { close(s.done) })
}

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

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Check the wrapped error for the real cause (EPIPE, ECONNRESET, timeout)
2. Stop writing once any Read/Write on the stream has failed — the conn is dead
3. Re-establish the tunnel at the application level; the stream has no in-stream recovery
4. Verify payload chunks stay under maxPacketData (the library already splits, so failure is transport-level)

if _, err := stream.Write(data); err != nil {
    conn.Close() // connection is dead; stop writing and reconnect
    return err
}

When it happens

Trigger: Calling Write after the peer disconnected; TCP send buffer failure (RST); writing concurrently with a keep-alive after connection teardown; write deadline exceeded.

Common situations: Peer or middlebox killed the connection while the proxy was uploading a large burst; application keeps writing after a prior read error marked the conn dead; NAT rebinding blackholes the flow.

Related errors

• read minecraft packet stream: %w
• write minecraft keep-alive: %w
• LRU size is bigger than subnet size
• write boolean: %w
• write UUID: %w

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