Fix io.netty errors when joining a Minecraft server
What common io.netty errors mean in Minecraft (connection refused, connection reset, read timed out, DecoderException) and how to fix each one.
Updated · 2 min read
Netty is the networking library Minecraft uses, so many connection problems show up as io.netty errors. The class name after io.netty tells you what happened. Find yours in the list below.
Quick reference
| Error contains | What it means |
|---|---|
AnnotatedConnectException: Connection refused | Nothing is listening at that address and port. |
ConnectTimeoutException | No answer at all from the address. |
ReadTimeoutException or Timed out | Connected, but the server stopped responding. |
Connection reset by peer or An existing connection was forcibly closed | The connection was cut, by the server or the network. |
DecoderException or EncoderException | The client and server did not understand each other's data. |
Connection refused
io.netty.channel.AbstractChannel$AnnotatedConnectException: Connection refused
The server is offline, still starting, or the player is using the wrong port. Confirm the server is running and use the exact address and port from the Network section. See connection timed out or refused.
Read timed out
Internal Exception: io.netty.handler.timeout.ReadTimeoutException
The player was connected, but the server sent nothing for around 30 seconds. Common causes:
- Server freeze. A huge lag spike, garbage collection pause or watchdog crash. Check
latest.logforCan't keep up!orThe server has stopped responding!. See Can't keep up. - World loading slowly when joining or teleporting into ungenerated terrain. Pre-generating helps. See pre-generate with Chunky.
- The player's connection dropping. If only one player gets it, it is likely on their side.
Connection reset
io.netty.channel.unix.Errors$NativeIoException: readAddress(..) failed: Connection reset by peer
java.io.IOException: An existing connection was forcibly closed by the remote host
The connection was closed abruptly. In the server log this usually just means a player closed their game or lost internet, and is harmless. If a player sees it repeatedly, the cause is often their network, VPN or antivirus, or the server crashing at that moment.
DecoderException and EncoderException
Internal Exception: io.netty.handler.codec.DecoderException: java.lang.IndexOutOfBoundsException
Internal Exception: io.netty.handler.codec.EncoderException: ...
The game received data it could not read. Usual causes:
- Mod mismatch on Forge: the client and server have different mods or versions. Make them identical. See mod and version mismatch errors.
- Version translation plugins like ViaVersion that are outdated. Update them.
- Oversized data, for example an item or book with huge amounts of data, or very large modded inventories. The error often mentions a size or
Packet too big. Removing the item or updating the related mod or plugin fixes it. - Client mods that change networking. Try joining with a clean profile.
"Internal Exception: java.lang.IllegalStateException"
Similar to decoder errors: usually a mod or plugin sends data the other side does not expect. Update both, and check that versions match.
Collecting details for help
- Note the exact error text the player sees.
- Check
logs/latest.logon the server at the same time for errors. - Note whether it affects one player or everyone.
Then post them in the Schokr Discord.