Reduce Minecraft server lag

Wispdock’s control panel isn’t built yet. Where a step says “in your control panel”, use whatever your host gives you for files, the console and start/stop. The Minecraft side works the same everywhere.

Which kind of lag

• Server lag: everyone sees it at once. Mobs freeze, broken blocks come back, the time of day jumps. The server is running below 20 ticks per second.
• Client lag: only you see it, as a low frame rate. The fix is on your PC: render distance, shaders, a performance mod such as Sodium.
• Network lag: one player has high ping while everyone else is fine. Usually their connection, or their distance from the server.

A quick test: open the F3 screen. If your FPS drops when the stutter happens, it’s your game. If several players complain at the same moment and /tps is below 20, it’s the server, and the rest of this guide applies.

Check the tick rate

The server runs the game in ticks, 20 per second when it keeps up. Each tick gets 50 ms. If a tick takes longer, the next one starts late and the whole world slows down.

On Paper, /tps shows ticks per second over the last 1, 5 and 15 minutes. /mspt shows how long ticks are taking (milliseconds per tick), as averages and peaks over the last few seconds and the last minute. On vanilla 1.20.3 and newer, /tick query shows the target rate and the average tick time. With spark installed, /spark tps works on any platform.

MSPT tells you more than TPS. TPS stops at 20, so a server showing 20 TPS could be using 12 ms per tick or 48. Our rule of thumb:

The log tells you too. Can't keep up! Is the server overloaded? Running 5032ms or 100 ticks behind means the server fell behind by that much. One of those during startup is normal. A steady stream of them is the problem you’re here for.

Find the cause with spark

spark is a profiler: it samples what the server thread is doing many times per second and adds it up. Recent Paper builds include it. On Fabric, Forge and NeoForge, install it as a mod from Modrinth or CurseForge. It doesn’t need anything on the players’ side.

/spark profiler start
/spark profiler stop

Start it, let it run for a few minutes while the lag is happening, then stop it. spark gives you a link to a report in its web viewer. If you’d rather not babysit it, /spark profiler start --timeout 300 stops by itself after five minutes.

Some lag isn’t constant. If the server is fine most of the time and freezes for a second now and then, record only the slow ticks:

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

That ignores every tick faster than 100 ms, so the report shows what the spikes have in common. Two other commands are worth knowing: /spark health prints TPS, MSPT, CPU, memory and disk use in one go, and /spark tickmonitor posts a line in chat whenever a tick runs long.

Read a spark report

The report is a tree of method calls with the share of time each one took. It looks dense, but you only need one branch of it.

1. Check the header: platform, Minecraft version and how long the sample ran. Thirty seconds of a quiet server won’t show you much.

2. Expand Server thread. That is the main game loop, and everything that makes ticks slow sits under it. The other threads (chunk workers, networking) rarely explain low TPS.

3. Follow the largest percentage down, one level at a time. Stop where one entry stops taking most of its parent’s time and splits into many small ones. That split point is usually your answer.

4. If a large share sits in a waiting or sleeping entry, the server had spare time during the sample. Profile again while the lag is actually happening.

Where the branch ends tells you what to fix:

• Entity ticking: too many mobs, villagers or items. See entity counts.
• Block entity ticking: hoppers, furnaces, modded machines. See redstone and hoppers.
• Chunk generation or loading: players exploring. See Chunky.
• A package name like com.example.someplugin: that plugin or mod is the cost. Check its config, update it, or try the server without it.

On plugin and mod servers, spark’s Sources view groups time by plugin or mod, which is the fastest way to see if one of them is to blame. If you want a second opinion, send us the report link.

View and simulation distance

Both live in server.properties and both default to 10. They control different costs.

Lowering simulation-distance to 6 or 8 saves the most CPU, and most players never notice. view-distance can stay a bit higher, since sending chunks costs less than ticking them. For a small survival group, simulation 6 to 8 and view 8 to 10 is a sensible start. Restart after changing either.

Two side effects to expect. An AFK farm only runs while a player is within simulation distance of it, so someone’s farm may stop working after the change. And players can’t see further than the server’s view-distance, whatever their own render distance says, unless they use a client mod that keeps chunks it has already seen. The server.properties guide covers the other settings in that file.

Pre-generate the world with Chunky

Generating new chunks is one of the heaviest things a server does, and players exploring in different directions make it worse. Chunky (a plugin for Paper, and a mod for Fabric, Forge and NeoForge) generates them ahead of time. While nobody is playing, run:

/chunky center 0 0
/chunky radius 5000
/chunky start

That generates a 10,000 by 10,000 block square around the centre. It can take hours and several gigabytes of disk. /chunky pause and /chunky continue stop and resume it, and it picks up where it left off after a restart. Afterwards, set a world border of the same size so nobody walks past the generated area:

/worldborder center 0 0
/worldborder set 10000

/worldborder set takes the full width, not the radius, which is why it’s 10000 here. If players spend time in the Nether, select it with /chunky world world_nether (on Paper) and run a smaller radius there too.

Keep entity counts down

Too many entities is the usual cause of lag on survival servers: big mob farms, hundreds of villagers, chickens left breeding, dropped items piling up. spark shows which types and where.

On Paper, /paper entity list counts entities by type. Add a type, like /paper entity list minecraft:villager, to see which chunks they’re in. On vanilla, /execute if entity @e[type=minecraft:villager] reports how many are loaded.

Talk to players about their farms before you delete anything. A smaller farm or a per-chunk cap usually fixes it. Villager trading halls deserve a look on their own: villagers pathfind and search for beds and workstations, which costs more than most mobs.

If you have to clear dropped items, /kill @e[type=item] removes every item on the ground in loaded chunks. Warn people first.

Redstone and hoppers

A hopper is a block entity that checks for items to move every tick. One hopper costs next to nothing. A storage system with a few thousand of them, or a sorter that runs all day, shows up clearly in spark as block entity ticking.

• Fast redstone clocks that run nonstop are the other common one. Ask players to add an off switch to clocks that only matter when someone is nearby.
• Water streams move items more cheaply than long hopper chains.
• A hopper powered by redstone is locked and stops moving items, which also stops most of its work.

Paper has settings for this in config/paper-world-defaults.yml:

hopper:
  cooldown-when-full: true
  disable-move-event: false
misc:
  redstone-implementation: VANILLA

disable-move-event: true skips the event plugins use to watch hopper movement. It’s faster, but plugins that protect or log hopper transfers stop seeing them. redstone-implementation: ALTERNATE_CURRENT is much quicker for large redstone builds, but a few contraptions that rely on vanilla quirks behave differently, so test the big ones afterwards. On Fabric, the Alternate Current mod does the same job.

spigot.yml also has ticks-per.hopper-transfer (default 8) and ticks-per.hopper-check (default 1). Raising them makes hoppers slower and cheaper, and it breaks redstone that depends on hopper timing. Leave them alone unless hoppers are clearly the top line in spark.

Paper settings worth knowing

Paper’s own settings live in config/paper-global.yml and config/paper-world-defaults.yml, with older ones in spigot.yml and bukkit.yml. A few that help on most servers:

• spawn-limits in bukkit.yml: lower monsters from its default of 70 if mobs are a large part of your spark report.
• entity-activation-range in spigot.yml: entities far from players are ticked less often.
• merge-radius in spigot.yml: dropped items and experience orbs close to each other merge into one entity.
• environment.optimize-explosions: true in paper-world-defaults.yml helps servers with TNT or a lot of creepers.
• chunks.entity-per-chunk-save-limit caps how many arrows, experience orbs and similar entities a chunk keeps when it saves.

Change one thing at a time and measure again with spark. If you change five settings and TPS improves, you won’t know which one did it, or which one broke the iron farm. The community Minecraft optimization guide by YouHaveTrouble on GitHub covers these settings in more depth. If you’re still on Spigot or vanilla, moving to Paper is often the biggest single gain: see Paper vs Spigot vs Purpur.

On modded servers

Performance mods help a lot. On Fabric: Lithium for game logic, FerriteCore for memory, C2ME for chunk generation. On Forge and NeoForge, ModernFix and FerriteCore are common. Many packs include them already, so check the mods folder before you add a second copy.

The profiling is the same. spark’s Sources view usually points at one mod: often a tech mod with a big automated base, or a worldgen mod making new chunks slow. Pre-generating with Chunky helps modded worlds even more than vanilla ones, since modded terrain is heavier to generate. The modpack guide covers matching mod versions between server and players.

When memory is the problem

More memory doesn’t fix low TPS. Ticks run on one main thread, so once the server has enough memory, extra RAM doesn’t make them any faster. A fast CPU core helps more.

Memory is the problem when the log shows java.lang.OutOfMemoryError, or when /spark health and the GC section of a spark report show long garbage collection pauses with memory sitting near the limit straight after a collection. Then raise -Xmx, and leave the machine some memory for Java itself. The RAM guide has sizes by player count and pack, and Aikar’s flags.

Wispdock’s draft plans are 4 GB for vanilla and plugins and 8 GB for modpacks. The pricing page has the details; prices are drafts and ordering isn’t open yet.

Still stuck? Send us the details and your latest.log.