Why is my Minecraft server lagging? A diagnostic checklist
Almost every laggy server has one of six problems. This is the order to check them in, and how to tell them apart — because the fix for a slow database is nothing like the fix for a runaway redstone clock.
The single most common mistake when a server starts lagging is changing settings at random. People lower view distance, restart, see no change, lower entity limits, restart again, and two hours later have a worse-configured server and the same problem.
Lag has a cause. Find it first.
1. Confirm it is actually the server
Type /tps. On Paper you will get three numbers — the average over 1, 5 and 15
minutes. 20 is perfect. Anything at or above 19.5 means your server is keeping up
and the problem is somewhere else entirely.
If TPS is fine but players complain about lag, you are looking at one of:
- Client-side lag — too many entities, particles or holograms being sent to players. Their frame rate drops; your server is fine.
- Network lag — high ping, packet loss, or a bad route to your host.
- Chunk loading — the world is streaming in slowly, which feels like lag but is a disk or generation problem.
A server at 20 TPS with players complaining is a different investigation to a server at 14 TPS. Do not skip this step — it eliminates half the possibilities in ten seconds.
2. Look at MSPT, not just TPS
TPS is a lagging indicator. It only drops after the server has already been missing its deadline for a while. MSPT — milliseconds per tick — is the real number.
The server gets 50 ms to finish each tick. Under 50 ms and it waits for the next one. Over 50 ms and it is late, and TPS starts falling.
| MSPT | What it means |
|---|---|
< 35 ms | Healthy, with headroom for player spikes |
35–50 ms | Working hard. One more farm and you are over |
50–100 ms | Over budget. TPS is falling now |
> 100 ms | Every tick is doing two ticks of work |
A server sitting at 48 ms looks fine on /tps and is one iron farm away from
falling over. Watch MSPT and you get weeks of warning.
3. Rule out garbage collection
If your lag comes in regular short freezes — a stutter every fifteen or twenty seconds, rather than constant slowness — suspect the JVM before you suspect any plugin.
Java periodically pauses everything to reclaim memory. A well-tuned server pauses for 20–50 ms, which nobody notices. A badly tuned one pauses for 300 ms or more, three times a minute, and players describe it as "random lag spikes".
The usual causes:
- Heap too small for the player count, so collections run constantly.
-Xmsand-Xmxset to different values, so the JVM keeps resizing the heap instead of settling.- Heap too large — yes, really. Give a server 32 GB when it needs 8 and each collection has far more memory to walk.
java -Xms12G -Xmx12G -XX:+UseG1GC \
-XX:MaxGCPauseMillis=200 \
-XX:G1HeapRegionSize=8M \
-XX:+ParallelRefProcEnabled \
-XX:+PerfDisableSharedMem \
-jar paper.jar noguiSet Xms equal to Xmx, and leave a couple of gigabytes for the
operating system. Never give the JVM all the RAM on the box.
4. Find the plugin doing it
This is where most guides say "disable plugins one by one until it stops". That works, and it costs you a whole evening plus several restarts in front of your players.
The faster route is a profiler. It samples the server thread thousands of times a second and builds a picture of where the milliseconds actually go.
The pattern to look for is blocking: a plugin that is not computing anything, just waiting. The classic case is a plugin running a database query on the main thread. The server cannot do anything else until the database answers, so every player on the server waits for one query.
In a profiler this shows up as a plugin holding a large share of tick time in something like
getConnection or executeQuery. The fix is almost always a config option
in that plugin (an async or cache setting) or a version upgrade — rarely something you fix yourself.
What to look for: a single plugin holding more than about 5 ms per tick, or any plugin appearing inside JDBC, HTTP or file I/O calls on the main thread. Both are bugs worth reporting to the plugin author.
5. Check entities and farms
Entity lag is real but widely misdiagnosed. People see "12,000 entities" and panic, when most of that number is nearly free.
What matters is tick cost, not count:
| Entity | Relative cost |
|---|---|
| Item frames, armour stands | Almost nothing — they barely tick |
| Dropped items | Cheap alone, expensive in piles (merge checks every tick) |
| Mobs with pathfinding | Expensive — each one runs AI every tick |
| Villagers | The most expensive common entity by a wide margin |
Eight thousand item frames are fine. Four hundred villagers in a trading hall are not. Look for concentrations, not totals — a single chunk holding a thousand entities is worth more of your attention than a world holding twelve thousand spread out.
6. Check redstone last, but do check it
Redstone is the cause people check first and understand worst. The instinct is to count components: "this build has 900 redstone parts, it must be the problem".
Component count is nearly irrelevant. What matters is how often redstone fires. A 900-block display that never changes costs nothing. A twelve-block observer clock ticking constantly can eat a fifth of your server's time on its own.
We wrote a separate guide on finding and fixing redstone lag, because it deserves more than a section.
Work in this order
- Check
/tps— is it even the server? - Check MSPT — how much headroom is left?
- Regular freezes? Fix the JVM flags first.
- Profile the server thread and find the plugin.
- Look for entity concentrations, not totals.
- Look for redstone activity, not components.
Most servers find it at step 3 or 4. Almost nobody needs to disable plugins one at a time.
Stop guessing which plugin it is
unlag.me samples your server thread thousands of times a second and names the exact plugin, machine or setting costing you ticks — then tells you what to change. Run one command in game and read it in your browser.