Fix Minecraft server lag: performance tips

Lag on a Minecraft server almost always comes down to one of three things: the server itself has too much work, a player's PC is too slow or the connection is bad. In this guide you first find out where the lag comes from. Then you make your server faster: measuring with spark, switching to Paper, setting the right distances, pregenerating your world and keeping mobs, farms and redstone in check.

Is it the server, the PC or the connection?

• Server lag: everyone notices it at the same time. Blocks reappear after you break them, mobs freeze for a moment and players get pulled back (rubber-banding). The server no longer manages 20 ticks per second.
• Low FPS: the picture stutters, but the world responds straight away. That's on the player's PC, and the server can't do anything about it.
• High ping: only that one player notices delay, for example when opening a chest. Check the ping in the player list (Tab). The Minecraft page has a ping test to our node in Amsterdam.

Only the first kind can be fixed on your server. That is what the rest of this guide is about.

Measuring Minecraft server lag: TPS and MSPT

A Minecraft server processes the world 20 times a second: 20 ticks per second (TPS). So each tick may take at most 50 milliseconds. How long a tick really takes is called MSPT (milliseconds per tick). When ticks take longer than 50 ms, TPS drops below 20 and players notice.

Since version 1.21, Paper comes with the spark profiler built in. Type in the console (without /):

spark tps
spark health

spark tps shows the TPS, the MSPT and CPU usage. spark health adds memory and disk usage. On an older version of Paper or Spigot, install spark yourself as a plugin.

Averaging below 20 TPS, or often above 50 MSPT? Then your server really has too much work. The old timings command is deprecated and on its way out of Paper. Use spark.

Find the cause with spark

Measuring only helps once you can see what eats the time. Start a profile while the lag is happening:

spark profiler start --timeout 600

After ten minutes the console gives you a link to the report. Open the Server thread in it and follow the percentages: the entries with the highest share take the most time. If you see a plugin's name, you know where to look. If you mostly see entities, chunks or hoppers, the settings further down will help.

Do you get the odd spike rather than constant lag? Turn on spark tickmonitor --threshold-tick 50. Every tick that takes longer than 50 ms is then reported. With spark profiler start --only-ticks-over 100 you record only those slow ticks.

Switch to Paper

Running Vanilla or Spigot? Switch to Paper. Paper is based on Spigot and builds on the same plugin API, so most Spigot plugins work on it as they are. Paper is designed to be much faster and has settings that Vanilla doesn't. Purpur is based on Paper and adds even more settings.

You switch through Versions in the game panel: see Change your Minecraft version or server type. Make a backup first and leave Wipe Server Files off, so your world stays.

When a Paper server is reinstalled, the panel puts our own optimised bukkit.yml, spigot.yml, config/paper-global.yml and config/paper-world-defaults.yml in place. Your own changes to those files are lost then, so make a backup first.

view-distance and simulation-distance

Two settings with a big effect are in server.properties. You open that file through Files.

• view-distance sets how much of the world the server sends to each player, measured in chunks in every direction. Default 10, allowed from 3 to 32.
• simulation-distance sets how far from players the server keeps updating mobs and other entities. Everything beyond it stands still. Also default 10, from 3 to 32.

So simulation-distance decides how much the server has to process every tick. view-distance mainly decides how many chunks are loaded and sent. A practical starting point for a busy server is view-distance=8 and simulation-distance=6. If MSPT stays high, go lower. Restart after every change.

Players who like to look far will notice a lower view-distance. A lower simulation-distance mainly shows with farms: they only run while a player is close enough.

Pregenerate your world with Chunky

Creating new chunks is heavy work for a server. When a player walks into unexplored land, the server has to generate those chunks on the spot. The Chunky plugin does that in advance, ideally before players join your server.

1. Install Chunky through Plugins in the game panel, or upload the.jar file yourself (see Install plugins). Then restart your server.
2. In the console, type chunky radius 5000. Chunky then generates a square up to 5000 blocks from the centre of your world (0,0). The default radius is 500.
3. Type chunky start. The console shows the progress and the expected duration.
4. chunky pause stops the work, for example when players log in. chunky continue picks it up again and chunky progress shows how far along it is.

A large radius takes a long time, and every chunk ends up on disk. Check on the Console page how much storage you already use before you pick a big radius. Then set a world border, so players don't end up outside the generated area. With a radius of 5000 that is worldborder set 10000: the number is the width of the border, not the radius.

Keep mobs, farms and redstone in check

Does the spark report mostly show entities? First see what is out there. paper entity list shows all entities currently being updated and paper mobcaps shows the mob limits of a world.

Paper controls this in config/paper-world-defaults.yml (the config folder in Files). These settings make a difference, each with the name as it appears in the file:

• entities.spawning.per-player-mob-spawns: defaults to true. The mob limit then applies per player instead of to the whole server. Leave it on.
• entities.spawning.spawn-limits: when a value is -1, Paper uses the limit from bukkit.yml (70 monsters and 10 animals by default). If mob farms are draining your server, set monster to 50, for example.
• misc.update-pathfinding-on-block-update: set this to false if you have many entities and run automatic farms or redstone clocks. According to Paper, this can make the server a lot faster.
• misc.redstone-implementation: ALTERNATE_CURRENT can greatly reduce the lag of redstone dust. It does change how redstone dust behaves, so some builds may work differently. Test it on a copy of your world first.
• hopper.ignore-occluding-blocks: at true, hoppers do less checking of where they can insert items.

spigot.yml has three more useful settings under world-settings.default: entity-activation-range (how many blocks from a player entities are updated normally), merge-radius.item (within how many blocks dropped items merge) and mob-spawn-range (how many chunks from a player mobs can spawn). Change one setting at a time and measure again with spark tps.

Check your plugins

A bad plugin, or a good plugin with a wrong setting, can drag TPS down on its own.

• Type plugins in the console and remove what you don't use.
• Look for plugin names in the Server thread of the spark report. A plugin at the top of the list is the first one to update, reconfigure or replace.
• Keep plugins up to date and check that they support your Minecraft version.
• Add new plugins one at a time. That way you see straight away which one causes the lag.

More RAM is not always the answer

Low TPS means the server has too much processing to do per tick. As long as there is free memory, more RAM won't fix that. Check memory usage on the Console page. According to Paper's documentation, Java doesn't use memory it doesn't need.

More RAM does help when memory sits at the maximum all the time, when you see OutOfMemoryError in the console or when you run a big modpack. How much you need per player count is in How much RAM does your game server need?.

You don't need to set Java flags yourself. The startup command of a Paper server in our panel already contains G1 settings based on Aikar's flags, and the memory follows your plan automatically. You can't add your own flags, so you can skip what older guides say about them. Do pick the right Java version under Docker Image in Startup: see Startup settings.

Schedule a daily restart

A restart at a quiet moment gives your server a clean start, with empty memory. Schedules does this automatically, with a warning to players a minute ahead. Pick a time when hardly anyone plays, for example 06:00.

When Budget is no longer enough

Budget and Premium run on the same AMD Ryzen 9 9950X nodes. Minecraft does most of its work on one thread, the Server thread from spark. For that, the speed per core counts, and it is the same on both. The difference is the number of cores: Budget has 1 core up to and including 5GB and goes up to 6 cores, Premium starts with 4 cores and goes up to 8.

Extra cores help with the work that happens next to the Server thread: generating and loading chunks while players explore, plugins that work in the background and Java's garbage collector. Does CPU usage on the Console page hit the maximum during busy hours, while your settings are already right? Then Premium is the next step. Read Minecraft Budget or Premium and compare the plans on the Minecraft page.

LagCore: our lag doctor

LagCore is our own lag doctor for Minecraft servers and networks. It is one plugin for Paper 1.20+ and forks such as Purpur and Folia, and it only sends measurements, never chat, commands or IP addresses. Watch the demo or request the add-on through the contact form. LagCore costs €10 per server per month.

Frequently asked questions

My server runs 20 TPS, but players complain about lag

Then the problem is on the player's side: low FPS on their PC or a high ping. Have them check their ping in the player list and run the ping test on our Minecraft page.

Which view-distance and simulation-distance are good?

That depends on your players and your plan. Start with 8 and 6, measure for a day with spark tps and adjust from there.

Which plugin is causing the lag?

Run spark profiler start --timeout 600 while the lag is happening. Look in the report for the plugin name with the highest percentage in the Server thread.

Does upgrading to more RAM help?

Only when memory in the panel is full or you see OutOfMemoryError in the console. If your CPU is at the maximum, extra cores (Premium) do more for you than more RAM.

Getting in touch through support or Discord? Include the link to your spark report.