Diagnosing lag

Three kinds of lag

• Server lag (low TPS). Everyone sees blocks reappear, mobs stutter, and chests take a moment to open. The server’s game loop cannot finish 20 ticks per second.
• Network lag (high ping). One player rubber-bands or takes damage late while others are fine. Their connection to Miami is slow or lossy.
• Client lag (low FPS). One player’s screen stutters, but the world reacts normally for everyone else. Their computer, not the server.

Ask players which of these they see; it tells you where to look.

Check TPS first

On Paper, run /tps in the console or in game as an operator. It prints the average ticks per second over the last 1, 5, and 15 minutes. 20.0 is perfect. Anything under about 18 is noticeable; under 15 is painful.

Also run /mspt on Paper to see how many milliseconds each tick takes. The budget is 50 ms; if the average is close to or above 50, the server is CPU-bound.

Find the cause with a profiler

Install the spark plugin (or mod, on Fabric and NeoForge). Then, while the lag is happening:

/spark profiler start --timeout 60

After a minute it prints a link to a report showing exactly which entities, plugins, or world regions are eating tick time. Most lag investigations end here.

The usual suspects

• Entities. Mob farms, item overflows, and animal pens. Run /spark healthreport or /paper entity list style checks, cull item drops, and cap farms. Paper’s per-world entity limits in config/paper-world-defaults.yml help.
• Chunks. High view distance and players exploring new terrain generate and keep many chunks loaded. Lower view-distance to 8 and simulation-distance to 6 in server.properties, and pre-generate the world with a plugin such as Chunky so exploration does not generate chunks live.
• Redstone and hoppers. Clocks and big hopper systems tick every game tick. Paper’s hopper settings in the world config reduce their cost.
• Plugins and mods. The profiler names them. Remove or replace the heavy one.
• CPU quota. In the panel, if the CPU graph sits at your plan’s quota during lag, the server wants more CPU than the plan allows. Reduce load first; upgrade if the workload is genuinely bigger than the plan.
• Memory pressure. Long garbage-collection pauses show up as periodic freezes with TPS otherwise fine. If memory use is pinned near the limit, move to a larger plan from your account; see choosing memory and changing plan size. The change keeps the same server, world, and address. Restart the server once it has applied: Java claims its heap at startup, so a running server keeps the old memory limit until you do.

When it is the network

Have the affected player run the latency check from the support page. Ping above 150 ms from their home to Miami cannot be fixed on the server. Wi-Fi, a VPN, or a congested connection are the usual causes on their side.

Quick wins, in order

1. view-distance=8, simulation-distance=6, restart.
2. Pre-generate the world within your border.
3. Cap mob farms and clear item overflows.
4. Profile with spark and remove the heaviest plugin or mod.
5. Only then, consider a bigger plan.