Minecraft server performance: lag, flags, view distance, Chunky and spark

A server that “lags” usually isn't short on hardware. More often there's one specific cause: a simulation distance that's too large, new terrain being generated, an overcrowded farm or a badly written plugin. We'll show how to measure lag, find its cause and fix it – from quick tweaks to Paper settings and profiling.

How to tell what's lagging#

A Minecraft server runs the game in ticks. It should get through 20 of them per second, which gives it 50 milliseconds per tick. Two numbers you need to know:

MSPT is the more precise indicator: a server with an MSPT of 45 ms still has 20 TPS, but no headroom at all. Once MSPT goes over 50 ms, TPS starts to drop.

You can check the values in the Console (type commands without a slash):

tps
mspt
spark tps

• tps – average TPS over the last 1, 5 and 15 minutes (Paper, Purpur).
• mspt – average, shortest and longest tick time (Paper, Purpur).
• spark tps – TPS, MSPT (minimum, median, 95th percentile, maximum) and CPU usage. Works anywhere spark is installed (Paper has it built in).

When the server can't keep up over a longer period, the console shows:

Can't keep up! Is the server overloaded? Running 2500ms or 50 ticks behind

The server is saying it's 2.5 seconds (50 ticks) behind and will skip those ticks. A single message at startup or while generating terrain is fine. If it repeats every few minutes, keep going with this guide.

Server lag or something else?#

Quick wins#

Sorted from the biggest effect to the smallest. You can do most of them in under ten minutes.

Startup flags and memory#

Flags are the parameters Java starts with. They set the memory size for the game (the heap), caps for memory outside the heap, and the behavior of the garbage collector, which clears unneeded data from memory. In the customer area you'll find them in the Startup tab, in the Startup flags section.

The customer area calculates the heap and caps itself based on your plan size, server type, Java version and the number of plugins or mods. It recalculates them when the server is created, after a plan change, after a type or version change, and before a start from the portal if any of these has changed since last time. It doesn't overwrite a startup command you've edited by hand in the panel or set as custom. If such a command has a heap larger than a smaller plan can handle, we won't start the server after the plan change (it would crash right away) and we'll email you.

All presets have the same safeguards: caps on network buffers, compiled code and loaded classes, MALLOC_ARENA_MAX=2 (fewer allocator memory arenas) and, from Java 17, -XX:TrimNativeHeapInterval (returns unused memory to the system). Purpur also automatically gets --add-modules=jdk.incubator.vector (faster calculations that Purpur can use).

Buttons in this section:

• Save – the settings are used on the next start.
• Save and restart – the server restarts right away. If it doesn't start with the new flags, the customer area reverts them and you'll see the message The flags are not compatible, reverted to the previous settings.
• Revert to previous – restores the last working settings.
• Use recommended – appears when the heap is too large for your plan or the startup command has no memory caps. It sets the recommended command.
• Recalculate now – recalculates the flags right away, so you don't have to wait for the next start from the portal.

Under Memory breakdown you can see how much goes to the heap and how much is left for everything else. After an automatic recalculation, the customer area shows something like We adjusted the startup to the new RAM size: heap 8.2 → 9.6 GB.

Running a server outside StormHost? The Startup script generator creates a startup script with the same calculation for Docker, Linux and Windows.

Why the heap isn't all of the RAM#

The heap (-Xmx) never grows past its own limit. What grows is memory outside the heap: network buffers, loaded plugin and mod classes, compiled code, threads and the system allocator. Network buffers grow the most – without a cap they can reach the size of the heap, so a server with a 6 GB heap can end up using 12 GB.

The server container has a hard limit 5% higher than the plan (10% for plans up to 4 GB, 15% up to 2 GB) and no swap. When the process goes over the limit, the system kills it. The Console shows Out of memory: true, and the server log has no error at all.

That's why every large part outside the heap has a cap, everything adds up with a margin below the plan size, and the heap gets the rest. When one part hits its cap, the server writes an error to the log (OutOfMemoryError: Direct buffer memory or Metaspace) instead of crashing silently, and that error points to the culprit.

The heap has the same minimum and maximum size (-Xms = -Xmx) and is allocated right at startup. That's why the memory graph in the panel shows a high number from the start. The panel also counts the world file cache, which the system frees when needed. A number close to the limit doesn't mean a crash on its own.

The Paper documentation recommends at least 6–⁠10 GB of heap regardless of player count, and warns that beyond a certain point, more memory doesn't improve performance.

View and simulation distance#

The world is split into chunks (columns of 16 × 16 blocks). The server keeps chunks loaded within a certain radius around each player:

• view-distance – how many chunks around the player the server sends to the game (what the player sees). Mainly affects memory and network.
• simulation-distance – the radius within which chunks are “alive”: mobs move, crops grow, redstone and farms work. Mainly affects the CPU, and therefore TPS.

The number of chunks grows with the square of the distance. With view-distance=10 the server keeps 441 chunks around each player, with 8 only 289 (a third fewer). The effect is the same for simulation.

Set them in the Server properties tab in the World group (all settings). We don't recommend a simulation distance below 5 – larger farms then stop working because part of the farm is outside the simulated area.

Paper settings#

Paper and Purpur have their own configuration in the config folder:

Always edit paper-world-defaults.yml. Open the file in the editor in the Files tab, find the existing section (for example chunks:) and change the value inside it. Don't add the same section a second time – with a duplicate key the server either refuses to load the file or uses only one of them, and your change won't apply.

Selected settings with the biggest impact on performance:

Here's what the changes look like in the file (only the changed parts; leave the other lines of the file as they are):

chunks:
  entity-per-chunk-save-limit:
    arrow: 16
    experience_orb: 16
    snowball: 8
    ender_pearl: 8
  prevent-moving-into-unloaded-chunks: true
collisions:
  max-entity-collisions: 2
entities:
  spawning:
    despawn-ranges:
      monster:
        hard: 72
        soft: 30
environment:
  optimize-explosions: true
misc:
  redstone-implementation: ALTERNATE_CURRENT
tick-rates:
  grass-spread: 4
  mob-spawner: 2

spigot.yml and bukkit.yml#

Paper also reads the older spigot.yml and bukkit.yml configuration files in the server's main folder.

spigot.yml#

All settings are in the world-settings › default section.

bukkit.yml#

Pre-generating the world with Chunky#

When a player reaches a place nobody has been before, the server has to generate the terrain. It's the most demanding operation of all: one player on an elytra can drag down the TPS of the whole server. The fix is to generate the terrain in advance and set the world border so players can't go beyond the prepared area.

The Chunky plugin generates terrain in the background, gradually, and you can pause it. It exists for Paper, Purpur and Folia, and as a mod for Fabric, Forge and NeoForge.

1. Install Chunky in the Plugins tab (for mods, Mods) › Browse: search for Chunky and click Install. Then restart the server (plugin guide).

2. In the Console, set the center of the world border:

   worldborder center 0 0

   • worldborder center – sets the center of the world border.
   • 0 0 – the X and Z coordinates of the center. Usually the center of the world, or the spawn coordinates.

3. Set the border size:

   worldborder set 10000

   • worldborder set – sets the border size.
   • 10000 – the diameter in blocks. The world will be 10,000 × 10,000 blocks, so 5,000 blocks from the center in each direction.

4. Pass the border to Chunky:

   chunky worldborder

   Chunky sets its center and radius from the world border.

5. Start generating:

   chunky start

   The console regularly shows the progress as a percentage, the number of generated chunks and an estimate of the remaining time.

Other commands:

The Nether and End#

The Nether is eight times smaller than the Overworld (1 block in the Nether = 8 blocks in the Overworld). For a border with a 10,000-⁠block diameter in the Overworld (radius 5,000), a radius of 625 blocks is enough in the Nether. Join the game, go to the Nether and type in chat:

/chunky world
/chunky center 0 0
/chunky radius 625
/chunky start

• /chunky world – without a name, selects the world you're currently in (the Nether).
• /chunky center 0 0 – the center of generation.
• /chunky radius 625 – the radius in blocks.
• /chunky start – starts generation.

Only set a world border in the Nether (/worldborder set 1250 typed in the Nether) on Paper and Purpur, and from version 1.21.9 elsewhere too – only from that version does each dimension have its own border. In older versions of Vanilla, Fabric and NeoForge, the command would also change the border in the Overworld.

The End can be generated smaller (for example a radius of 2,000–⁠3,000 blocks); players move mostly around the islands there.

After a server restart, generation doesn't resume on its own. Continue with chunky continue (or set continue-on-restart: true in plugins/Chunky/config.yml).

Diagnostics with spark#

spark is a profiler: while the server runs, it records what the server is doing and shows the result as a clear tree with percentages. Paper has it built in from version 1.21 (so does Purpur); on Fabric and NeoForge, install the spark mod from Modrinth. On a Velocity proxy the command is sparkv.

Quick overview#

Profiling step by step#

1. Wait until the server lags (or until it has its usual number of players). A profile of an empty server shows nothing.

2. In the Console, start the profiler for 10 minutes:

   spark profiler start --timeout 600

   • spark profiler start – starts the profiler.
   • --timeout 600 – stops it automatically after 600 seconds (10 minutes) and uploads the result.

3. Wait 10 minutes. A link to the profile (spark.lucko.me/…) appears in the console.

4. Paste the link into the Spark profile analyzer. It shows what's slowing the server down and what to change.

You don't have to upload the profile: with the --save-to-file option (for example spark profiler start --timeout 600 --save-to-file), spark saves it as a .sparkprofile file in the plugins/spark folder (on Fabric and NeoForge config/spark). Download it in the Files tab and upload it to the analyzer.

To stop the profiler early, type spark profiler stop. For short spikes (the server occasionally “freezes” for a second), use:

spark profiler start --only-ticks-over 100

• --only-ticks-over 100 – records only ticks longer than 100 ms. It filters out normal operation and leaves only the “laggy” ticks. Choose a value between 50 and 100.

How to read the result#

If you want to go through the tree yourself, open the profile link in your browser:

1. In the thread list, expand Server thread – the main game thread. Problems in other threads (chunk loading, networking) are less common.
2. Click to expand nodes and watch the percentages. Always follow the path with the highest share.
3. Time spent in Thread.sleep() or “parked” is fine – the server is waiting for the next tick because it has headroom.
4. Typical findings:

5. In the top bar, switch the view to Sources – it shows a separate tree for each plugin or mod, so you can see right away which one causes the most load.

You can send the profile link to the plugin's author or to our support. It contains no passwords or server files.

How many entities are on the server#

On Paper, the paper entity list command prints entity counts by type. In the console you also need to specify the world:

paper entity list * minecraft:overworld
paper entity list minecraft:villager minecraft:overworld

• paper entity list – lists entities.
• * – no filter; lists all entity types with counts (the first number is ticking entities, the second non-ticking).
• minecraft:villager – a filter for one type. The output then shows the coordinates of the chunks with the most of these entities.
• minecraft:overworld – the world (minecraft:the_nether, minecraft:the_end for the other dimensions). In the game you don't need to specify the world; the one you're standing in is used.

Then go and look at the spot in the game and make the farm or pen smaller.

Performance mods (Fabric and NeoForge)#

Fabric and NeoForge don't have Paper's optimizations, but there are server-side mods with the same goal. You'll find all of them on Modrinth (in the Mods tab › Browse):

Always pick the mod for your exact Minecraft and loader version. Details are in Mods and modpacks.

When it's time to upgrade#

Upgrading your plan makes sense when:

• spark shows that the load is spread evenly (no single plugin or farm dominates) and MSPT stays above 40 ms with your usual number of players,
• spark health shows memory constantly at the cap and the garbage collector can't keep up,
• you're adding a large modpack or planning for many more players.

If one plugin or farm takes most of the time, more performance won't fix it – you need to remove the cause.

Verify it works#

1. After your changes, restart the server and let it run with players for at least 15 minutes.
2. Type spark tps. MSPT (median) should be under 50 ms, ideally under 35 ms, and TPS 20.
3. The Can't keep up! message should no longer repeat.
4. If you're unsure, run another 10-⁠minute profile and compare it with the previous one.

Troubleshooting#

The server won't start after a config change#

Most often it's a YAML error (a tab, wrong indentation, a duplicate section). Look in the console for a line with the file name and line number. Fix it, or delete the file – Paper recreates it with default values on startup (your changes are lost). Alternatively, restore a backup.

The flags are not compatible, reverted to the previous settings.#

The server didn't start with the new flags and the customer area reverted them. Check your custom flags (a typo, a flag for a different Java version) and try the preset without custom flags.

The server suddenly shuts down with no error in the log#

A typical sign of exceeding the memory limit. The Console shows the lines Exit code: 137 and Out of memory: true, and the customer area shows The server ran out of memory and the system stopped it. above the console. The panel starts the server once more; if it crashes again within a minute, it leaves it off.

1. In the Startup tab, check the warnings next to the startup flags. If the heap is too large for your plan or the command has no memory caps, click Use recommended.
2. The customer area doesn't overwrite a startup command you've edited by hand or set as custom. Use the recommended preset, or set the heap according to the table in Why the heap isn't all of the RAM.
3. Look in the log for OutOfMemoryError: Direct buffer memory or OutOfMemoryError: Metaspace. They point to a plugin or mod that fills the network buffers or keeps loading classes over and over.
4. If the crashes continue even with the recommended settings, look for a memory leak: spark heapsummary shows what takes up the heap, and spark profiler start --alloc --timeout 300 shows what allocates the most memory. Paste the link into the Spark profile analyzer, or send it to our support.

java.lang.OutOfMemoryError: Java heap space#

The heap is full. Either there's more on the server than fits in memory (a modpack, a large number of players), or a plugin or mod is “losing” memory (a memory leak). An upgrade helps, or finding the leak with spark heapsummary. You'll find more errors in Common Minecraft server errors.

Chunky reports an invalid world#

The world name doesn't exist. In the game, use /chunky world without a name (it selects the world you're standing in), or in the console enter the name of the main world from level-name (default world).

A redstone build stopped working after enabling ALTERNATE_CURRENT#

Some circuits rely on Vanilla's update order. Set misc.redstone-implementation back to VANILLA and restart the server.

Further reading#

• Profiling in the Paper documentation (opens in a new window)
• Paper world configuration (opens in a new window)
• spigot.yml configuration (opens in a new window)
• bukkit.yml configuration (opens in a new window)
• Aikar's flags in the Paper documentation (opens in a new window)
• spark commands (opens in a new window)
• Chunky commands (opens in a new window)