Lag diagnostics & auto-tune
Find the chunks and plugins that cause lag, read performance history, get staff lag alerts, and let auto-tune lower the load when the server struggles.
On this page
When players say "the server is lagging", this page helps you answer two questions: where the lag happens and what causes it. Every tool here only measures; nothing changes gameplay except auto-tune and the lag shield, which you have to turn on yourself.
Quick routine when the server lags
- Check the current state with
nusa status. - Measure the cause with
nusa lagchunks start 30. - Read the report: the most expensive chunks and plugins.
- Visit the top chunk with
/nusa lagchunks tp 1and look at what is there (farms, hoppers, piled-up mobs). - If lag keeps coming back, look at the pattern with
nusa perfandnusa lagspikes.
Finding expensive chunks and plugins (/nusa lagchunks)
nusa lagchunks start 30
nusa lagchunks status
nusa lagchunks report 20| Command | What it does |
|---|---|
/nusa lagchunks start [seconds] | Starts measuring for 5–300 seconds (default 30) |
/nusa lagchunks status | Shows the progress of the measurement |
/nusa lagchunks stop | Ends the measurement early |
/nusa lagchunks report [rows] | Shows the last report again (up to 50 rows) |
/nusa lagchunks tp <rank> | Teleports you to a chunk from the last report |
/nusa lagchunks history [n] | Earlier reports, kept across restarts |
Each report row shows the world and chunk, its time per tick (ms/tick), its share of the measured time, the dominant category and the most expensive type in that chunk, for example minecraft:hopper.
What is measured: entity ticks, block entity ticks (hoppers, furnaces and similar), scheduled block and fluid ticks, random ticks and natural mob spawning. Chunk loading and networking are not counted per chunk.
The report also has a Plugins section: the time each plugin spends in scheduled tasks and event listeners, with its most expensive task or event.
Performance history (/nusa perf and /nusa lagspikes)
/nusa perfshows right now, the last hour and the last day: TPS, average and peak MSPT, peak players, entities, loaded chunks and the number of lag spikes./nusa lagspikes [page]lists every lag spike, newest first: when, the peak, how long and the cause./nusa lagspikes info <n>shows one spike in detail, and/nusa lagspikes tp <n>takes you to its most expensive chunk.
History is stored in nusa-perf/history.json (the last 24 hours and the last 100 spikes), so it survives restarts.
Lag alerts for staff
Staff with the nusaspigot.alerts permission (OP by default) get chat messages:
- When lag starts: average ms per tick, TPS and whether the cause is being measured.
- When the measurement finishes: the main cause and its share, the most expensive chunk and plugin, with Teleport, Full report and Details buttons.
- When the server recovers: how long the lag lasted and its peak.
Type /nusa alerts off to mute alerts for yourself until the next restart, and /nusa alerts on to turn them back on.
Auto-tune: lowering the load automatically
Auto-tune is off by default because players can notice it. When it is on, it lowers the server load a little at a time while the server struggles, then gives it back once the server recovers.
It takes steps in this order, starting with what players notice least:
- Reduce the entity activation range (distant mobs are ticked less often).
- Reduce the simulation distance.
- Reduce the view distance.
Auto-tune never goes below the minimums you set, and never edits server.properties or spigot.yml. When the level returns to 0 (and at shutdown), every world gets its own values back.
nusa autotune
nusa autotune on
nusa autotune offnusa autotuneshows the current level, thresholds, minimums, the last change, and each world's current and original values.nusa autotune onstarts auto-tune without changing the config file (until the next restart).nusa autotune offrestores every world and stops auto-tune until the next restart.
Default thresholds: one step down after 10 seconds in a row at 45 ms or more, one step back after 60 seconds in a row at 35 ms or less.
Next steps
- Want alerts in Discord? See Cloud panel & server presets.
- Lag caused by players exploring? Generate chunks in advance with World pre-generation.
- Learn about the built-in optimizations in Performance & optimization.