spark: find out where the lag on your Minecraft server comes from
spark is the standard profiler for Minecraft servers: it measures which code, which mod or which chunk is eating your tick time, so you do not have to guess. A server runs 20 ticks per second, so every tick gets 50 milliseconds. If a tick consistently takes longer, your TPS drops and everything feels sluggish. With /spark profiler, /spark tps and /spark heapsummary you usually have a concrete suspect within five minutes.
What does a profiler actually do?
A profiler looks many times per second at what your server's main thread is doing, and notes the full call chain: from the main loop, through the component currently taking its turn, down to the exact method in a plugin or mod. Thousands of those snapshots together show where the time is going. That is called sampling, and it is exactly why spark puts almost no load on your server.
The difference from guessing is huge. "That plugin feels heavy" is a hunch; "a third of the tick time goes into mob pathfinding in one spot" is a measurement. spark will not fix anything, it only points at where the problem sits.
How do you install spark on your server?
spark exists as a plugin for Bukkit, Spigot, Paper and Purpur, as a mod for Fabric, Forge and NeoForge, and as a build for proxies such as BungeeCord and Velocity. Do grab the right variant: a plugin file does nothing in a mods folder.
- Type
/spark tpsin the console first; some server software already ships with spark. - Otherwise download the right build: the plugin belongs in
plugins/, the mod inmods/. - Upload it through your panel's file manager or over SFTP. In a Pterodactyl panel you can drag it straight in.
- Restart the server completely. Do not use
/reload, which on Paper causes more problems than it solves. - Give yourself permission with LuckPerms:
/lp user YourName permission set spark true. Without the permission node, only the console can use it.
spark is free and open source, and there is a good reason it appears in every list of core plugins alongside EssentialsX, LuckPerms and CoreProtect.
What do /spark tps and /spark health tell you?
/spark tps gives you TPS over the last 5 and 10 seconds and over 1, 5 and 15 minutes, plus the MSPT: how many milliseconds a tick really costs. MSPT is the more honest number, because TPS stays at 20 for as long as the server just about keeps up. 20 TPS at 45 ms is a very different thing from 20 TPS at 12 ms: the first one collapses the moment ten more players join.
For MSPT you also get a median and higher percentiles. /spark health adds CPU usage, memory usage, time spent in garbage collection and free disk space.
| Measurement | Guideline | What to do with it |
|---|---|---|
| MSPT under 30 ms | Headroom left | Nothing, you have room to grow |
| MSPT 30 to 50 ms | Tight | Run the profiler before it goes wrong |
| MSPT above 50 ms | TPS drops below 20 | Run the profiler while the lag is happening |
| Low median, high 95th percentile | Spikes | Look for autosave, chunk generation or a timed task |
How do you run /spark profiler at the right moment?
The golden rule: profile while the lag is happening. A report from a quiet Sunday morning says nothing about the Friday-evening peak. Start with /spark profiler start, let it run for three to five minutes and finish with /spark profiler stop. You get a link to an online viewer that you can share with your team or with support.
A few options make all the difference:
--timeout 300stops automatically after 300 seconds, for when you forget to.--only-ticks-over 100only includes ticks that took longer than 100 ms. Ideal for stutters while your average MSPT is perfectly fine.--thread *profiles every thread, not just the main one. On modded servers, chunk generation often sits in separate threads.--allocmeasures memory allocation rather than time: which code produces the most rubbish.
During the session, have a player fly to the problem area; a short report is far quicker to read than an hour of noise.
How do you read a spark report without getting lost?
The viewer opens with a tree. At the top sits the server's main loop at roughly 100 percent. That number tells you nothing, because by definition all the time goes there. So keep expanding the heaviest sub-branch until the percentage breaks up into ten twigs of a few percent each. The last branch that still takes a substantial share is your suspect. If you see 60 percent in a branch simply called "tick", you have not gone deep enough.
Two things speed that up. spark can attribute measured time to its source, meaning the plugin or mod the code came from; that gives you a top three within ten seconds. And package names help: if you see net.minecraft, the server is doing vanilla work such as entities, chunks and redstone. Do be careful though: a plugin that spawns a thousand mobs shows up as the cost of mobs, not as the cost of that plugin.
Which causes come out on top in practice?
Four findings cover most of the reports we see.
Too many entities in one place
Mob farms with no kill mechanism, hundreds of loose items in a tunnel, a pile of boats on the spawn plaza. In the report, time drains away into ticking entities or into mob spawning. Paper can show per world how many entities of which type sit where; teleport over there and it is immediately obvious.
A plugin doing something every tick
A classic: a scoreboard or hologram that refreshes twenty times a second and loops through every player as it does. With ten players you notice nothing, with eighty it sits right at the top. Going from every tick to once per second is a factor of twenty, if the plugin lets you.
Hopper chains
Hoppers constantly check whether something is above or beside them. Long rows under full chests and sorting systems dozens of blocks long add up fast. Paper has options to temper those checks, and often part of the chain is redundant anyway.
A view-distance set too high
Every step up costs quadratically more chunks per player; the default value of 10 means 21 by 21 chunks around everyone. Because simulation-distance is set separately, you can let players see far while only nearby entities and redstone keep ticking. Often the cheapest win available.
| view-distance | Chunks per player | Difference against 10 |
|---|---|---|
| 12 | 625 | +42 percent |
| 10 (default) | 441 | reference |
| 8 | 289 | -34 percent |
| 6 | 169 | -62 percent |
What you do next is covered in our article on optimising your Minecraft server and reducing lag. Change one thing at a time and measure again, otherwise you will never know which adjustment worked.
When do you need /spark heapsummary?
/spark heapsummary shows what is in memory at that moment: per class the number of objects and the number of bytes, sorted by size. You reach for it when memory keeps creeping up, when garbage collection causes long pauses, or when the server slows down after a few hours while a restart fixes everything.
The answer is often in the top ten lines: millions of entity objects point straight back at that same overcrowded farm. With heavy modpacks it is simply a matter of volume: All the Mods 10 runs on NeoForge with Minecraft 1.21.1 and 400 to 500 mods, and asks for at least 10 GB of RAM, 12 GB for a small group and 14 to 16 GB with five or more players and plenty of automation. FerriteCore saves 30 to 40 percent memory there; Canary and ModernFix pitch in on the same loader.
Be honest about the limits: heapsummary is a snapshot, not a leak analysis. If you want to know exactly which object is holding onto something, you need a heap dump plus a tool like Eclipse MAT. Specialist work, and rarely necessary for an ordinary survival server.
When does spark not help you?
Is your TPS at 20 and your MSPT comfortably under 50 ms while players complain about rubberbanding? Then the problem is not in the tick loop but in the connection: packet loss, a bad route or an attack. spark has /spark ping for that, which lines up your players' ping side by side. If that points at something malicious, our article on handling DDoS attacks on your game server will be more useful than a profiler.
spark also will not tell you whether your hardware is simply too slow. Minecraft leans heavily on a single core, so an old processor with lots of cores disappoints. If what you mostly see is vanilla tasks all running slightly too long, with no clear outlier, you have run out of configuration to change and faster hardware is the honest conclusion. With Minecraft hosting from MC-Node, the budget line runs on AMD EPYC 7443P and the premium line on AMD Ryzen 9 9950X, and the latter is built for servers hitting a single-thread wall.
Frequently asked questions
Does spark itself cost performance? Barely. spark works by sampling and takes snapshots rather than counting every call. Feel free to leave it installed permanently; with no active session it does virtually nothing. Only during /spark profiler is there a small extra load.
Does spark work on modded servers too? Yes, there are builds for Fabric, Forge and NeoForge. On a pack like All the Mods 10, which runs on NeoForge and Minecraft 1.21.1 and requires Java 21, spark is even more valuable: with 400 to 500 mods, guessing is hopeless. Do use --thread * there.
What is the difference between /spark tps and /spark profiler? /spark tps is the thermometer: it tells you whether the server is keeping up and what a tick costs. /spark profiler is the investigation that tells you why. Start with tps and health, and run the profiler while the problem is happening.
Should I install ClearLagg if spark finds a lot of entities? You can, but it is a plaster: ClearLagg clears items periodically while the farm producing them keeps running. Fix the source first and use ClearLagg as a safety net, not the other way round.