XTLS/Xray-core · error

read minecraft keep-alive: %w

Error message

read minecraft keep-alive: %w

What it means

packetStream.Read received a packet with ID 0x04 (configuration keep-alive) but failed to decode its single Long (8-byte big-endian) payload. Since readPacket already delivered the body, this indicates the body is shorter than 8 bytes or otherwise malformed — a framing/state mismatch with the peer, not an I/O failure.

Source

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

			payload, ok, err := parseCustomPayload(packet)
			if err != nil {
				return 0, err
			}
			if !ok || len(payload) == 0 {
				continue
			}

			n := copy(p, payload)
			if n < len(payload) {
				s.pending = append(s.pending[:0], payload[n:]...)
			}
			return n, nil
		}

		if packet.packetID == configurationKeepAlive {
			var id Long
			if err := packet.readFields(&id); err != nil {
				return 0, fmt.Errorf("read minecraft keep-alive: %w", err)
			}
			if s.isClient {
				if err := s.writeKeepAlive(id); err != nil {
					return 0, err
				}
			}
		}
	}
}

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

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

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Pin both endpoints to the same library/protocol version
2. Confirm the endpoint is actually an xmc-compatible peer, not a vanilla Minecraft server
3. Capture the stream and verify 0x04 packets carry exactly 8 payload bytes
4. Close the connection; mid-stream decode corruption is not recoverable

n, err := stream.Read(buf)
if err != nil && strings.Contains(err.Error(), "read minecraft keep-alive") {
    // protocol mismatch: peer is not speaking the expected configuration state
    conn.Close()
}

When it happens

Trigger: Peer (client or server) writes a 0x04 packet whose data section is under 8 bytes, or the two sides disagree on packet ID assignments so a different packet is interpreted as a keep-alive.

Common situations: Version mismatch between client and server xmc builds that reassigned configuration packet IDs; a non-xmc Minecraft endpoint responding in the wrong protocol state; corrupted stream after middlebox interference.

Related errors

• read minecraft custom payload channel: %w
• read minecraft custom payload data: %w
• write minecraft keep-alive: %w
• empty domain name
• authentication rejected

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