Fixing Minecraft server lag: what to measure and in what order

Measure before you change anything

Minecraft servers run the world on one thread, twenty times a second. Every one of those ticks has 50 milliseconds to do all its work. Everything below follows from that.

Two numbers describe it:

• TPS, ticks per second. Capped at 20. It cannot be better than normal, only worse.
• MSPT, milliseconds per tick. How much of the 50 ms budget a tick actually used.

MSPT is the one to watch. TPS only falls once ticks have already overrun, so it reports damage after it happens. MSPT at 45 ms tells you that you are one busy moment away from trouble, while TPS still reads a comfortable 20.

Run /tps on any Paper-based server. If MSPT sits above about 40, you have a problem whether or not TPS has noticed yet.

Get a profile, do not guess

Every serious answer to "why is my server slow" comes from a profiler, and the standard one is spark. It is a plugin or a mod depending on your platform, and it produces a report naming the exact method that is eating the tick.

/spark profiler start
  ... let it run through a period of real lag, several minutes ...
/spark profiler stop

It gives you a link to a shareable tree. Read it top down: the widest branch is where the time goes. This turns "the server is slow" into "this specific thing is taking 22 ms per tick", which is a problem you can actually fix.

Everything below is what that report usually says.

The usual causes, in the order they usually appear

Too many entities

Item stacks on the ground, mobs in a farm, minecarts, armour stands, boats left in the water. Entities are ticked individually, and a few thousand of them will end your tick budget on their own.

Fix: cap mobs per chunk in your server config, set item stacks to merge and to despawn, and go and look at the coordinates the profiler points at. There is usually one build responsible.

View distance and simulation distance

Chunk loading and chunk ticking scale with the square of these numbers, so they are the highest-leverage settings on the whole server.

Set view distance to what players need to see, around 8 to 10. Set simulation distance lower, around 5 to 6. Players can see much further than the game needs to simulate, and separating the two is free performance that nobody notices losing.

One plugin

A single plugin doing something expensive on every tick, or hitting a database synchronously on the main thread, will show up as a named branch in the spark report. Chunk-scanning plugins and anything that saves player data on every movement event are the usual suspects.

Fix: update it, configure it to do less, or replace it. If the profiler names a plugin, the plugin's own issue tracker is the right next stop.

Redstone and hoppers

Hoppers check their contents constantly, and a large sorting system is thousands of hoppers doing that at once. Complex redstone clocks are the same problem in a different shape.

Fix: this is a conversation with your players rather than a config change. Most server platforms expose hopper tick rate settings, which help without breaking builds.

World generation

Generating new chunks is the single most expensive thing a server does. A player flying at speed into unexplored terrain generates chunks faster than the server can keep up with.

Fix: pre-generate the world out to your border with a plugin such as Chunky, once, while nobody is on. Set a world border so the map has an edge. Both are one-time costs that remove a recurring one.

Garbage collection

If the profiler shows time going nowhere in particular and you see periodic freezes rather than steady slowness, it is the garbage collector.

Fix: usually a smaller heap rather than a larger one, and a newer Java version, which ships a better collector. See how much RAM a server needs for why bigger is not better, and the Java version checker for what your Minecraft version supports.

What will not fix it

More RAM. Lag is the main thread running out of time, not the server running out of memory. Adding heap to a server that has enough makes collection pauses longer.

More CPU cores. Vanilla and Paper run the world on one thread. A machine with 32 slow cores is worse than one with 8 fast ones. Single-thread performance is what matters, which is the opposite of what most hosting plans advertise.

Folia is the exception: it splits the world into regions that tick in parallel, so it does use cores. It only helps when players are spread out, and it breaks plugins that assume one main thread. See choosing server software.

Restarting on a timer. This hides a leak rather than fixing it, and it hides the evidence you would need to find the leak.

A working order

1. Check MSPT, not TPS.
2. Run spark through a real period of lag.
3. Read the widest branch of the report.
4. Fix that one thing.
5. Measure again.

Steps 4 and 5 are the ones people skip. Changing five settings at once and finding the server faster teaches you nothing about which of the five mattered, and you will be back here next month.