Fix "Internal Exception: java.io.IOException" in Minecraft
This error means the connection between a player's client and your Minecraft server broke mid-message. Here is how to tell a bad home connection from a plugin, a proxy or a restart.
6 min read · Updated Oct 21, 2026 · By GuavaHost Team
The full message a player sees usually looks like one of these:
Internal Exception: java.io.IOException: Connection reset by peer
Internal Exception: java.io.IOException: Broken pipe
Internal Exception: java.io.IOException: An existing connection was forcibly closed by the remote host
Internal Exception: io.netty.handler.timeout.ReadTimeoutException
All of them say the same thing in different words. Minecraft sends data in packets (small, numbered chunks of data) and expects every packet to arrive whole and in order. Something cut the stream off part way through, so the client gave up and dropped the player back to the server list.
Notice what the error does not say: it is not "server offline" and not "refused". The connection existed and then stopped. That narrows things down a lot.
Step 1: Work out who it happens to
Before touching any config, answer one question: is it one player, some players, or everyone?
| Who gets it | Where to look first |
|---|---|
| One player, every time | That player's connection or client |
| Several players, randomly | Your server's packet sizes, a plugin, or the node under load |
| Everyone, at the same moment | The server restarted, crashed or was stopped |
| Everyone, only on a proxy network | The proxy's forwarding settings |
If it is one person and everyone else is fine for hours, you can stop reading the server logs. Their connection is the problem, and the fixes are in the last section.
Step 2: Read the server side
Sign in at customer.guavahost.com, open My servers, click Manage on your server and open the Console tab. Type IOException into the search box above the log to filter it down.
What you find tells you which cause you have.
- Nothing at all about that player. The disconnect happened on the player's side before your server noticed. Their network, their client, or something between the two.
Disconnecting <player>: Internal Exceptionwith a packet name after it. Something your server sent was too big or malformed. That is usually a plugin or a mod.- Dozens of lines at once, followed by
Stopping serveror a crash report. The server went down and took everyone with it. The error players saw is a symptom, not the cause. Go and read the real crash instead: How to read server logs and crash reports shows you where to start. ReadTimeoutExceptionfor a player who is clearly still online. Their client stopped replying for long enough (30 seconds by default) that your server hung up.
Step 3: The oversized packet problem
This is the cause people never guess, and it is common on plugin and modded servers.
Minecraft has a hard limit on how large a single packet may be. Anything that sends unusually large chunks of data can trip it:
- A plugin writing a huge amount of text, a long book or a very large inventory GUI.
- Custom map art, maps with enormous amounts of item data, or shulker boxes nested with thousands of items.
- A mod syncing a large config or recipe list to the client on join.
- A world edit or schematic plugin streaming a big paste to nearby players.
The giveaway is that the disconnect happens at a predictable moment: on join, when a specific menu opens, or when a specific player walks into a specific place. The console often names the packet class right before the disconnect.
To find it, remove or disable the newest plugin or mod and test again. If you cannot narrow it down by hand, a profiler helps: Find what is causing lag with spark is built for performance, but its thread view also makes it obvious which plugin is doing the work when the drop happens.
Step 4: Proxies and networks
If your server sits behind Velocity or BungeeCord, IOException is the normal symptom of a forwarding mismatch, because the proxy and the backend disagree about the shape of the handshake.
Check that:
- The forwarding mode matches on both sides. Velocity's modern forwarding needs the same secret file on the proxy and on every backend server.
- The backend servers have
online-mode=falseinserver.properties, and the proxy handles authentication instead. - Nobody can reach the backend servers directly. A player connecting straight to a backend port gets exactly this error, and it is also a security hole.
Run a Minecraft network with Velocity or BungeeCord covers the settings in full. If you are not running a proxy, skip this section entirely.
Step 5: Restarts, when everyone drops at once
If every player is dropped at the same instant and the console shows a clean shutdown, your server simply restarted. A scheduled restart does this on purpose. So does a crash, an out-of-memory kill, or pressing Restart at the top of the server page.
Scheduled restarts are a good thing, they just need warning. Most plugin platforms can broadcast a countdown first, and players who expect a restart do not report it as a bug.
Step 6: Fixes for a single player
When it is one person, work down this list with them.
- Switch network. Wi-Fi to a cable makes more difference than anything else here. Packet loss on Wi-Fi is the single most common cause.
- Leave a mobile hotspot or VPN. Both add loss and latency, and some VPNs mangle UDP and TCP traffic in ways Minecraft dislikes.
- Close bandwidth hogs. A large game download or a 4K stream in the background on the same connection will do it.
- Restart the router. Unglamorous, and it works often enough to be worth doing early.
- Check their mods. Client-side performance and networking mods are a frequent cause. Ask them to try vanilla, or the modpack with nothing extra.
- Lower their render distance. A client that cannot keep up with chunk data sometimes times out while loading in.
If they still cannot get in, look at whether they can reach the server at all. Your friends cannot connect: a checklist that finds it separates a connection problem from an address problem, and double-check they have the right address from Finding your server IP and port.
One thing that is not the cause: distance on its own. A player 300ms away has a laggy but playable game, while a player with 2 per cent packet loss and 40ms ping gets dropped. Loss is the thing that matters here, not latency.
Common questions
Is java.io.IOException my fault or the player's?
Most of the time it is the player's connection, especially if everyone else is playing happily at the same moment. It becomes your server's problem when several players get it at the same predictable point, such as on join or when a particular menu opens, which points at a plugin or mod sending too much data.
Does more RAM fix an IOException?
No, not by itself. Memory and network are separate problems, and adding RAM changes nothing about packet loss. The exception is a server that is crashing from running out of memory, because then the disconnect message players see is just the server dying.
Why does it only happen when I join, never to my friends?
That pattern almost always means your own client or connection. Try a wired connection, turn off any VPN, and test the server with a plain unmodded client. If a vanilla client on a cable connects fine, the culprit is in what you removed.
Can a plugin really kick people off the server?
Yes. Anything that sends an unusually large packet to a client, such as a huge inventory menu, a very long written book, or a schematic paste, can exceed Minecraft's packet size limit and force a disconnect. Removing the newest plugin and testing again is the quickest way to prove it.
Still stuck? Jump into our Discord at discord.gg/GuavaHost and the team will help you out.
- minecraft
- java
- connection
- ioexception
- troubleshooting
Host a Minecraft Java server From $3.99/mo, with instant setup and DDoS protection.
Still need help? Our team is online 24/7 to answer questions.