Minecraft server lag: finding the culprit with spark and timings

"The server is lagging" usually means one of three things: the server can't keep up, a player's computer is slow, or a player's connection is bad. Only the first one can be fixed on the server. Here's how to tell them apart and find the culprit with a profiler instead of removing plugins one by one.

First: whose lag is it

A server needs 20 ticks per second, which means at most 50 ms per tick. On Paper and Purpur, /tps shows the average over 1, 5 and 15 minutes and /mspt shows tick time. If TPS is 20 and MSPT sits well under 50, the server is fine and the problem is on the player's side.

Taking a spark profile

spark shows where the main server thread spends its time. Recent Paper builds ship with it; on older versions you install it like any plugin. You need spark permissions or op.

1. Wait for the lag. A profile of an empty server at 6 am shows nothing.
2. Start the profiler.
3. Wait 2 to 5 minutes so the lag happens several times.
4. Stop it. spark gives you a link to a report that opens in the browser.

/spark profiler start
/spark profiler stop

You can set the duration in seconds up front so you don't have to stop it. If the lag comes in rare spikes, add the flag that only records ticks longer than a given number of milliseconds, so normal ticks don't drown out the picture.

/spark profiler start --timeout 300
/spark profiler start --only-ticks-over 100

Reading the report

The report is a call tree. You want the main thread, called Server thread. Expand the node with the largest percentage and keep going down until you hit a name that makes sense.

• A plugin name or its package, like com.author.plugin. A plugin is eating the time. Look deeper at what exactly: an event handler, a timer task, a database call on the main thread.
• Entity ticking. Too many mobs, dropped items, armor stands, minecarts.
• Hoppers and redstone. Player builds. Next step is finding the spot on the map.
• Chunk loading and generation. Players running into new land. Pre-generation and a world border help; we covered that in the hosting and memory article.
• World saving. Autosave is stuck on a slow disk.

Look at the share of time, not how often a name shows up. A plugin at 3% is background noise. A plugin taking half of the laggy ticks is suspect number one.

Other spark commands

When timings still matter

Timings is the older built-in report from Spigot and Paper. Newer Paper versions deprecated and removed it in favor of spark. If you're on an old server version and spark won't run for some reason, you take a report like this:

/timings on
(wait a few minutes under load)
/timings paste

Timings measures in big blocks: plugin, event, task. spark goes deeper, down to the method. If you have the choice, use spark.

Finding the spot in the world

If the profile points to entities or contraptions, you need to find where they are. A vanilla command counts entities of a type across the server:

/execute if entity @e[type=minecraft:item]
/execute if entity @e[type=minecraft:villager]

It answers with a count. Swap in armor_stand, minecart or hopper_minecart. Paper also has /paper entity list, which shows entities by type and the most crowded chunks. Then teleport there and have a word with whoever built the farm.

Common mistakes

• Profiling without lag. A report from a quiet hour tells you everything is fine.
• Removing plugins at random. Five gone, the lag stays, players lost half the features.
• /kill @e without a type. It kills villagers, pets, armor stands, item frames and players too.
• Throwing memory at it. If the tick is long because of a farm, more gigabytes won't help. Add memory when spark shows you're short and garbage collection never stops.
• Cleanup plugins. Wiping every dropped item each minute treats the symptom and annoys players.
• Confusing lag with ping. TPS is 20 and one player complains. The server isn't the problem.

Doing the same thing faster

spark takes the profile, and Cloud Panel doesn't replace it. It removes the running around. The main screen shows whether the server is up and how many players are online, next to the machine's disk and memory load. You send spark commands from the console in the same window, without joining the game or opening SSH.

Once you have a suspect, switch it off in the plugins section: the panel doesn't delete the jar, it moves it to a separate folder. Restart with a button, check TPS, bring the plugin back if it wasn't the one. Config edits you make while fixing lag go into the log and can be rolled back if things get worse.

Checklist

1. You know whether it's the server or a player: /tps and /mspt checked.
2. The profile was taken during lag, 2 to 5 minutes long.
3. Server thread is expanded and the biggest node found.
4. The culprit has a name: plugin, entities, contraption, chunks or saving.
5. If it's a place in the world, you found it by entity count.
6. One change at a time, a new profile after each.
7. TPS holds 20 in the evening at peak online.

Console, server status and one-click plugin toggling in one window: 3 days free.