How to Fix Lag on a Paper Server

Short answer

Confirm the server is actually Paper with /version, take a spark profile during the lag, and fix whatever the profile names: entity spawning, chunk loading, hoppers or a plugin. If /tps reads 20.0 while players stutter, it is the network or their client, not Paper.

Lag on Paper has its own set of causes, because Paper has its own set of settings. An entity pile-up that vanilla shrugged off may now be capped, a chunk-loading issue has its own configuration section, and the profiler tells you which of them you are looking at.

This guide is the Paper-specific diagnosis: verify the software, read the profile the way Paper expects, work through the four causes that appear most often, and stop at the point where the profile says you are done.

Before you start

Operator access
Spark, which Paper recommends and documents
A way to restart the server after each change

1. Confirm what is actually running

Ask the server, not your memory. /version prints the server brand and version, and version.json in the server root records it too. Some hosts call a vanilla service "Paper" in a menu, and a paper-weight-fork or a patched jar behaves slightly differently from stock Paper.

If the brand is not what you expected, every setting in this guide may be in the wrong place, so it is worth the ten seconds.

in game or console

/version

2. Read the spark profile rather than guessing

Paper's own documentation says the only command you should rely on for performance information is /spark. Start a profile, let the server run the way it runs when players are on and complaining, and stop it.

The report is a ranked list of what uses tick time. Work down it: the largest entry is the thing to fix, and fixing it usually reveals the next one. Fixing in the wrong order wastes the whole evening.

in game or console

/spark profiler start
# wait for the lag
/spark profiler stop
/tps
/mspt

Chunk generation at the top: players are exploring ungenerated territory. Pre-generate with Chunky and set a world border.
One entity type or chunk at the top: a farm or spawner. Cap it, clear the accumulated drops, or redesign it.
A plugin at the top: update it, configure it, or remove it. Plugins do not get faster for being loved.
Everything flat and small: nothing is wrong on the server, and the problem is elsewhere. Go to the network step.

3. Fix the entity and chunk causes the profile names

Entity spawning is Paper's biggest configurable source of tick time. Lower the caps, keep per-player spawning on, and pull the despawn ranges in. Chunk loading is the second: view-distance and simulation-distance in server.properties multiply everything, and pre-generating the map removes generation from the tick entirely.

Hopper arrays are the third common entry, because every full hopper retries every tick. The cooldown setting lets it rest, and reducing how many hops a chain makes is worth more than any configuration value.

config/paper-world-defaults.yml

entity:
  spawning:
    spawn-limits:
      monsters: 40
    per-player-mob-spawns: true
  despawn-ranges:
    softer:
      monsters:
        horizontal: 32
        vertical: 8
chunks:
  min-chunk-unload-count: 50
hopper:
  hopper-transfer: 8
  cooldown-when-full: true

server.properties

view-distance=6
simulation-distance=6

4. Check the plugins, then rule out the network

If a plugin is named in the profile, update it first: many lag issues in a long-running server are a plugin that has not kept up with the Minecraft version. If it is current, configure it or remove it. Remember that every plugin also holds memory for the whole time the server is running, so removing one helps twice, at startup and on every tick.

Two Paper-specific things are worth checking before you blame the profile. Command blocks and scoreboards keep running whether or not anyone is playing, and the config has per-world controls for both. And if the profile shows a lot of time in chunk loading rather than in any one chunk, the fix is pre-generation rather than a setting.

in game or console

/plugins
/paper chunkinfo

5. Confirm the fix and stop

Restart, let the server settle, and take a fresh profile during the same kind of session as the first one. Compare /tps and /mspt with the same number of players. If the numbers moved, you know which change did it and which one did nothing.

Stop at a steady 20.0 with headroom. A Paper server that holds its tick rate on one core with a few players is doing what it should, and further tuning only trades away view distance, mob density or plugin features for numbers nobody can feel.

in game or console

/tps
/mspt
/spark profiler start

Good to know

Paper's /tps and /mspt commands work, and its documentation describes both, but it points to spark for anything beyond a quick reading.
Paper settings only take full effect after a restart, except /paper reload for the configuration files. Do not judge a change from the console command alone.
Configuration is per world. If you changed the default and one world is still slow, check that world's own paper-world.yml, which overrides it.
How to optimize Paper is the longer version of this diagnosis, including the JVM flags and pre-generation.

Common questions

Is my Paper server lagging because of Paper?

Rarely. Paper is faster than vanilla or Spigot on the same hardware, so a Paper server that lags is usually doing more work than the machine can: more entities, more chunks, more plugins. The spark profile names which.

Should I increase view distance on Paper?

Only if you have measured headroom. View distance multiplies the chunks in play, so raising it is the most expensive lever in the config. Raise it one step and profile again rather than doubling it.

Why is TPS fine but players still lag?

The server is keeping up, so the delay is between the player and the server, or on their client. Check their connection, their render distance, and whether anyone else experiences it. Server-side tuning cannot fix a network problem.

Do Paper config changes need a restart?

Configuration files are re-read with /paper reload. Changes in server.properties need a full restart, and plugins always do. Take /tps readings after the restart to see the effect.

How do I know my Paper server is healthy?

A steady 20.0 in /tps, MSPT comfortably below 50, and a spark profile with no single entry dominating. Hold that during your busiest sessions, not on an empty server at midnight.

Sources

Official documentation this guide was checked against.

Rather not run this on your own machine? PufferHost gives every player a free Minecraft server with 3 GB of RAM and 10 slots. Create a free server.