Internal Exception: io.netty.handler.codec.DecoderException
A DecoderException disconnect means the client and server disagree about what packets look like. Usually a mod mismatch or an out-of-date optimiser.
The short version
Internal Exception: io.netty.handler.codec.DecoderException means the client and server disagreed about what a packet should look like, so one side could not read it. The usual causes are a mod present on one side but not the other, mismatched mod versions, an out-of-date optimisation mod, or a corrupted world chunk.
An Internal Exception: io.netty.handler.codec.DecoderException (sometimes with a long stack trace below it) means the connection between your client and the server got a packet it did not understand and dropped you. It is almost never the server's fault on its own; it is a mismatch between the two ends.
#The four common causes
Mod mismatch. One side has a mod the other does not, or has it at a different version. Forge tells you this loudly at the join screen; Fabric and Quilt sometimes fail quieter and produce a DecoderException instead. Open Dashboard → your server → Files → /data/mods, list the mods, and make sure your client folder matches exactly (same files, same versions).
Resource pack too large or corrupted. Server resource packs above 250 MB or with a bad zip header can fail mid-transfer and show up as a decoder error after the loading bar finishes. Disable the pack temporarily in Files → /data/server.properties by clearing resource-pack= and try again.
A misbehaving plugin. Plugins that inject custom packets (custom titles, custom GUIs, anti-cheat) can send a packet the client cannot parse if the client is on a different protocol version. Remove the most recently installed plugin from Files → /data/plugins and restart.
An outdated optimiser mod on the client. Sodium, Lithium, OptiFine, and a few performance forks lag behind Minecraft release. After a Minecraft update, the client mod can stay on the old packet format for a week or two. Update the client-side optimiser, or pin back to a Minecraft version both ends agree on.
#Reading the trace
The line after DecoderException usually names the packet that failed. If it includes a mod or plugin's package name (net.minecraft. is vanilla; com.someauthor. is third-party), that is your culprit. Pull that mod from the server (or the client if you can identify which side sent the bad packet) and restart.
#Where to go next
- Outdated client or outdated server if it is a clean version mismatch.
- Minecraft server won't start if the server itself is also crashing.
#Frequently asked questions
How do I fix io.netty.handler.codec.DecoderException?
Match the mods exactly on both sides, including versions. If the mod lists already match, update optimisation mods, which are the most frequent single cause because they change packet handling and break when versions drift apart.
Can a corrupted world cause a DecoderException?
Yes. A malformed chunk can produce a packet the client cannot decode, and the disconnect happens when the player walks into that area. The tell is that it always happens in the same place rather than on join.
Does this error mean my connection is bad?
No. This one is about the shape of the data rather than whether it arrived. A bad connection produces a timeout; a DecoderException means the data got through and did not make sense.
Written and maintained by the Hostd engineering team. Last updated 2026-05-23. Notice a mistake? Tell us.