How to Fix io.netty.handler.codec.DecoderException on a Minecraft Server

Direct answer

`io.netty.handler.codec.DecoderException` means incoming packet data could not be decoded. Read the nested cause and compare the client/server version, mods, plugins, proxy, and protocol translators; do not treat the Netty wrapper itself as the root cause.

Diagnosis to use: A DecoderException is a wrapper; the nested “Caused by” line often identifies a malformed packet, unsupported payload or a protocol compatibility problem.

What it means

Trace packet decode errors to version, mod, plugin, proxy, or protocol mismatches without guessing.

What to collect: Capture the complete exception and both protocol versions. Check whether the error happens to one account, one modded client, or every player, and whether a proxy or ViaVersion-style packet plugin is in the path.

If you are a player

• Copy the complete disconnect text and save your client latest.log from the failed join.
• Verify the Minecraft version, loader/modpack release, and any protocol-changing client mods match what the server expects.
• If possible, try the intended clean/known-good client profile. Tell the owner whether the same account can join other servers.

If you run the server

1. Capture the complete nested exception from the server/proxy/client logs; the outer packet/Netty message is usually only a wrapper.
2. Confirm the exact client, server, proxy, and protocol-translation versions involved in the failing connection.
3. On a test copy, remove or update packet/protocol-changing plugins or mods one at a time until the failure stops.
4. Do not “fix” malformed packet data by randomly changing compression or timeout settings unless the underlying error specifically points there.

Targeted repair: Test one change at a time on staging: matching client/server versions, removing a recently changed protocol transformer, or reproducing without the proxy. Do not blindly increase network limits to hide malformed packet errors.

Verify after the change: Rejoin from the previously affected client and confirm that the same action or item no longer triggers the decode failure.

Important notes

• Packet exceptions often wrap the real cause. Keep the full nested exception and identify the first plugin/mod/protocol component named in it.

References

Use the documentation for the exact software and release you run. These sources support the settings or diagnostic behavior used in this fix.

• PaperMC: Basic troubleshooting

Related fixes and guides