Why your Minecraft server lags — and how to find the cause

A Minecraft server runs in ticks: 20 per second, 50 ms each. When a tick doesn't fit into 50 ms, TPS drops and everyone lags at once. Don't guess the cause — measure it: /mspt shows your headroom, the spark profiler shows who ate it. The usual suspects are entities, redstone, new chunk generation, too high a view distance, or one specific plugin.

Server, network or client#

Players say "lag" about three different problems. Each has a different fix, so figure out which one you have first.

A server can't raise a player's FPS, and a powerful gaming PC won't save anyone from low TPS. The rest of this article is about server-side lag.

TPS and MSPT: the 50 ms budget#

TPS (ticks per second) is how many ticks the server completes each second; 20 is normal. MSPT (milliseconds per tick) is how long a tick takes. For 20 TPS, MSPT has to stay below 50.

MSPT is more useful than TPS because it shows headroom. TPS never goes above 20: at an MSPT of 15 or 45 it reads the same, but in the second case you're 5 ms away from lag. Watch MSPT at peak hours — it warns you before players start complaining.

/spark tps
/mspt
/spark health

/spark tps shows TPS and CPU usage, Paper's /mspt shows average, minimum and maximum MSPT over the last 5, 10 and 60 seconds, and /spark health gives an overall report: TPS, CPU, memory and disk.

The spark profiler: finding the culprit#

Since 1.21, Paper ships with spark built in — there's nothing extra to install. The profiler records what the server is busy with for a few minutes and gives you a link to the report.

1. 1

   Wait for the lag

   A profile is only useful while the problem is happening. Take it at peak online or when players complain.

2. 2

   Start the profiler

   /spark profiler start --timeout 600 stops on its own after 10 minutes and posts a link. For rare freezes add --only-ticks-over 100: only ticks longer than 100 ms make it into the report.

3. 3

   Open the server thread

   In the report pick "Server thread" — the main thread that runs the tick. Look for the thickest branches: that's where the time goes.

4. 4

   Switch to the Sources view

   The Sources view builds a separate tree for every plugin, so you see right away how much of the tick each plugin takes.

/spark profiler start --timeout 600
/spark profiler start --only-ticks-over 100
/spark profiler open
/spark profiler stop

Common causes of lag#

Entities and farms

Mob farms, hundreds of animals in pens, piles of items on the ground, minecarts — every entity is processed every tick. /paper entity list shows which entities you have most of and in which world, and /paper chunkinfo shows how many chunks are loaded.

Redstone

Fast clocks, huge contraptions and piston farms load the tick even when nobody's around, as long as their chunks stay loaded. A spark profile shows what they really cost.

New chunk generation

Building a new piece of the world — terrain, caves, structures, lighting — is one of the most expensive things a server does. Players flying elytras into unexplored land can easily drop TPS for everyone. The fix is a world border plus a pre-generated world: see pre-generating your world.

View and simulation distance

view-distance sets how many chunks around a player the server sends to the client, simulation-distance the radius in which entities get updated. Both default to 10. Lowering simulation-distance directly cuts tick work; more in the server.properties guide.

Plugins

One badly written plugin can eat the whole tick. Don't remove plugins at random: spark's Sources view shows who spends what, so you remove or replace the culprit instead of half your setup.

Memory and garbage collection

When memory is tight, Java keeps pausing for garbage collection — players see that as regular short freezes. /spark gc shows the collection history, /spark health how full memory is. How much to allocate and which flags to use is in how much RAM your server needs. Extra memory won't make the tick faster, though.

CPU

Paper runs the game tick on a single main thread, so a fast core matters more than many cores. On cheap hosting with an overloaded CPU, MSPT is high even on an empty server — then only a better plan or a different host helps, see shared hosting or a VPS.

What about the anticheat?#

An anticheat can cause lag too if it does heavy work on the main thread. You check it the same way: find it in the Sources view of a spark profile and see how much time it takes from "Server thread".

DGuard runs its checks on network threads, not the main thread, so TPS stays at 20. On a live server it's 0.03% of one core on the main thread: 0.38 ms of a 10.9 ms tick with 121 players. To check it on your own server, run /dguard perf — it shows how much time the checks take. How to measure any anticheat's load is covered in how much an anticheat costs your server.

FAQ#