Skip to content

Fix "Failed to decode packet" in a mod

A custom packet (a payload) is written to bytes by one side and read back by the other. When the reading doesn’t match the writing, the connection drops with Failed to decode packet '...', or Failed to encode packet '...' on the sending side. The name in quotes is the packet.

Checked on 19 November 2026: each message on this page is in Minecraft 1.21.1’s own code. A decode failure needs a client connected to a server, so it wasn’t reproduced for this page.

  • The codec reads different fields from those it writes, or in another order. Writing an int and then a string, but reading the string first, fails.
  • Client and server run different versions of the mod, and the packet changed between them. Install the same version on both.
  • A field that can’t be sent as is, such as a value that is sometimes null without an optional codec for it.
  • Too much data in one packet. The game limits a packet’s size; the log then says Payload may not be larger than, followed by the limit (1048576 bytes for some payloads in 1.21.1). Send less, or split it.

Open the payload’s codec and check that each field is read in the same order and with the same type as it is written. On NeoForge and on Fabric 1.20.5 and newer, a StreamCodec that lists each field once does both directions, so they can’t drift apart (NeoForge: payloads).

Crash Doctor in Linen reads the crash report and the log next to it, then names the mod, the line and what to change. It’s free. Send data from the server to a player and from a player’s game to the server show a payload with one codec.