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.
Common causes
Section titled “Common causes”- The codec reads different fields from those it writes, or in another order. Writing an
intand 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
nullwithout 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).
In Linen
Section titled “In Linen”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.