Find the cause of Minecraft server lag with spark

Players do not need spark in their own game. On Fabric and Forge it is a server side mod; see install mods for uploading it. On Paper the built-in copy steps aside when you install the spark plugin yourself.

Run the commands from the Console tab without the slash, or in the game with a slash as an operator. Other staff need the spark permission, which you can give with LuckPerms.

spark tps

The output has three parts:

A tick has 50 milliseconds. When the median is under 50 but the maximum shoots to several hundred, the server has spikes: short freezes, often from a save, a big explosion or garbage collection. When the median itself is above 50, the server is behind all the time.

If TPS is 20 and players still feel lag, the cause is on their side: ping or low frames. A profiler run on the server will not find it.

spark health
spark health --memory

spark health adds memory use, disk space and garbage collection to the TPS lines. With --memory it also lists the memory pools of Java.

• Memory near the maximum, all the time: the server is short of memory. Long garbage collection pauses follow.
• Memory going up and down in a saw tooth: normal. Java fills memory and cleans it up.
• Many old generation collections in `spark gc`: memory pressure. See how much RAM a Minecraft server needs.

1. Wait until the lag is there. A profile from a quiet moment shows nothing useful.
2. Type spark profiler start --timeout 120 in the Console. spark records for 120 seconds.
3. Keep playing as normal. Ask players to do what they did when the lag started.
4. After the timeout spark stops by itself and prints a link to the report.
5. Open the link in your browser.

Without --timeout, stop the run yourself with spark profiler stop. spark profiler cancel throws a run away without a report.

For lag that comes and goes, use --only-ticks-over with a value above 50 and let it run longer, such as 10 minutes. The report then shows only the slow ticks, so the normal ticks do not hide the problem.

The report is a tree. The top node is the server thread, and every branch below it shows a share of the time. Expand the biggest branch step by step until you reach a name you recognise.

Switch to the Sources view at the top of the report to group the time by plugin or mod. That view answers the question "which plugin is it?" in one look.

Percentages are a share of the recorded time, not of one tick. A plugin at 30% of a server that runs at 60 ms per tick costs about 18 ms per tick, more than a third of the 50 ms budget.

spark heapsummary

This posts a report that lists every kind of object in memory, with the count and the size. It pauses the server for a moment while it counts, so run it once, not in a loop.

• Many entity or item objects: a farm or item pile in a loaded chunk.
• Many chunk objects: a high view distance or players spread over the map.
• A class with a plugin or mod name that keeps growing between two summaries: a likely memory leak in that plugin or mod.

Compare two summaries, one shortly after a restart and one hours later. What grew is what to look at.

On Paper, paper entity list counts entities per type and world, which pairs well with a profile that points at entities.

When a report points at something you cannot place, send the link to support with the time the lag happened. We answer every day from 07:00 to 23:00 Central European Time.