“The server is lagging” is four different problems and they have different fixes. Guessing which one you have is how admins end up upgrading hardware that was never the bottleneck.
A profiler tells you instead of you guessing, and the one most servers use is spark.
The four kinds of lag
Separate these before touching anything, because the symptom people report is the same for all four.
Tick lag. The server cannot finish its work inside a tick. Everything in the world slows down together – mobs move oddly, farms produce less, redstone runs late. This is what TPS measures.
Network lag. The server is fine, the connection is not. Rubber-banding, delayed block breaking, actions that take effect a second after you do them. TPS looks perfect.
Client frame rate. The player’s own machine. Everyone else is fine. This gets reported as server lag constantly.
Chunk loading. Terrain arrives slowly when exploring. A different subsystem from tick lag and fixed by different mods – chunk generation performance rather than tick optimisation.
A profiler distinguishes the first from the rest in about two minutes, which is the entire reason to run one.
What spark is
A performance profiler for Minecraft clients, servers and proxies, with three parts: a CPU profiler for diagnosing where tick time goes, memory inspection for diagnosing memory problems, and health reporting for overall state.
It is designed to run in production. That is the important property – it is light enough to leave installed and profile a live server while players are on it, rather than needing a reproduction on a test instance.
It runs on Fabric, NeoForge, Forge and Quilt as a mod, and on the Bukkit family as a plugin, with both client and server side optional. Current release reached 26.x on 19 September. GPL-3.0.
How to actually use it
- Install it. Start a profile while the problem is happening, not afterwards – a profile of a healthy server tells you nothing.
- Let it run for a few minutes under real load.
- Stop it. spark produces a link to a web viewer rather than a wall of text in console.
- Read the tree from the top. The viewer shows which parts of the tick consumed what share of the time, nested.
Step four is where people stop, because the output looks like a stack trace. It is not – it is a tree of time. You are looking for one branch that is unreasonably large, and there almost always is one.
What the common answers look like
A handful of causes account for most tick lag on ordinary servers, and each has a recognisable signature in a profile.
- Entity count. A large share of time in entity ticking usually means a mob farm, a chunk full of items, or a herd of animals nobody culled.
- A specific mod. One mod’s package showing up disproportionately is the clearest result a profile can give you, and the one most worth having.
- Chunk work. Generation and loading dominating means players are exploring, and the fix is pre-generation rather than tuning.
- Redstone. A single always-on clock somewhere in the world, usually forgotten.
Entity count is the most common and the easiest to fix, and it is also the one people least expect because nothing looks wrong.
Memory, which is a different problem
The other half of spark is memory inspection, and the symptom set is different: periodic freezes rather than constant slowness, getting worse the longer the server runs.
That pattern is usually garbage collection, and the usual causes are a heap that is too small for the workload or one that is far too large. More memory is not automatically better – a very large heap produces longer pauses when it is collected.
The heap size that suits a server depends on player count, view distance and mod list, and it is the setting most often set badly on both ends. The server specs breakdown covers what to allocate.
Before you profile
Three things are worth checking first because they are free and they are frequently the answer.
View distance and simulation distance. These are multiplicative with everything else and a server set to 16 when 10 would do is paying for that constantly.
Whether the world is pre-generated. An unexplored world is generating terrain on demand, forever.
How many chunks are force-loaded. Claims mods and some farms hold chunks permanently, and it accumulates invisibly – a reason to limit forceloading in a claims setup.
Short version
- Establish which of the four kinds of lag you have before changing anything.
- Install spark and profile while the problem is happening.
- Read the profile as a tree of time and look for the one oversized branch.
- Entity count is the most common cause and the easiest fix.
- More RAM is not a general solution and sometimes makes pauses worse.
The tuning that follows a profile is the same work covered in the tuning guide – the difference is that you now know which part of it to do.
Images: Programmer Art Fix project gallery.