Compatibility
Minecraft: Java Edition
Platforms
Tags
Creators
Details
CheckLags
Find out where your server is lagging and what might be causing it.
spark can tell you which plugin or task is putting pressure on your server. But sometimes that's only half the picture. You might know that entities or chunk loading are causing problems, but still have no idea where it's happening.
That's what CheckLags is designed to help with.
CheckLags scans loaded chunks, ranks them by estimated lag impact, and gives you an idea of what's happening in each hotspot. Whether it's a mob farm, dropped items, a large number of hoppers, block entities, or frequent chunk loading, you can narrow down the areas worth investigating.
What is CheckLags?
CheckLags is a server-side diagnostic tool that helps you track down the physical locations behind server performance issues.
It monitors tick times in the background and starts investigating loaded chunks when it detects sustained low TPS or unusually slow ticks.
Here's what happens:
- CheckLags measures tick duration using Paper's
ServerTickEndEvent. If spark is available, its MSPT statistics are used as an additional reference. - When performance drops or tick spikes occur, CheckLags starts scanning loaded chunks.
- Each chunk receives a relative heat score based on its contents, such as entities, dropped items, block entities, and chunk-loading activity.
- Results are collected into a ranked list so you can see which areas are worth investigating.
When the server is running normally, the scanning process stays idle. It only becomes active when there's a performance issue to investigate.
A note about the scores: Chunk heat is an estimate, not an exact measurement of how many milliseconds a chunk consumes. Minecraft and Paper distribute tick work in ways that don't allow reliable per-chunk timing through the available APIs.
Features
Lag hotspots
Find the chunks that are most likely contributing to your server's performance problems.
/lagcheck topdisplays the hottest loaded chunks, ranked by their estimated impact.- Click a result to teleport directly to the corresponding location.
/lagcheck watchcontinuously displays the three hottest chunks while you investigate.- Each hotspot includes a possible explanation, such as mob activity, item accumulation, block entities, or chunk loading.
/lagcheck inspectprovides a closer look at a 3×3 chunk area, including its most common block-entity types.
Folia support
CheckLags supports Paper, Purpur, and Folia using the same plugin jar.
Folia requires a different approach to accessing world data, so chunk scanning is handled through the owning region thread.
Additional Folia features include:
- Runtime detection of Folia.
- Region-safe chunk scanning.
/lagcheck regionto compare your current region's TPS with global TPS.- Region TPS information displayed alongside chunk results in
/lagcheck top.
This makes it easier to identify whether performance issues affect the entire server or are concentrated in a particular region.
TPS alerts
CheckLags can notify staff when server performance drops below configured thresholds.
- Default warning threshold: 18 TPS.
- Default critical threshold: 10 TPS.
- Separate cooldowns prevent repeated notifications.
- A recovery message is sent when TPS returns to normal.
- Alerts are sent only to players with
checklags.alerts.
Alerts intentionally contain no coordinates or chunk information. This makes them suitable for staff who are streaming or sharing their screen and don't want to expose player bases.
Players can also disable their own notifications with /lagcheck alerts off.
spark integration
CheckLags works without spark, but having it installed provides additional performance information.
When spark is available, CheckLags uses its public statistics API for more responsive TPS and MSPT readings.
With spark integration, /lagcheck stats can also display:
- TPS and MSPT statistics.
- Process and system CPU usage.
- Garbage collection activity and pause information.
- Spike count and loaded chunk information.
This can help distinguish between problems caused by activity inside the world and issues related to CPU usage or garbage collection.
CheckLags supports both bundled spark (included with Paper, Purpur, and Folia 1.21+) and the standalone spark plugin, including cases where spark loads after CheckLags.
If spark isn't available, the plugin automatically falls back to Paper's tick APIs. The active statistics source is always shown in /lagcheck stats.
Commands
All commands use /lagcheck. The aliases /lags and /clag are also available.
| Command | Description |
|---|---|
/lagcheck top [world] [rows] |
Displays the hottest loaded chunks, along with current TPS. Results can be clicked to teleport to a hotspot. |
/lagcheck watch [seconds] |
Continuously displays the top three hotspots. Default duration is 120 seconds. Run again to stop. |
/lagcheck inspect [world] [cx] [cz] |
Scans a 3×3 chunk area and reports entities, items, block entities, chunk loads, common block-entity types, and plugins responsible for force-loaded chunks. Without arguments, uses your current location. |
/lagcheck region |
Shows the TPS of your current region compared with global TPS. Folia only. |
/lagcheck stats |
Displays platform information, spark status, TPS/MSPT, CPU usage, GC activity, spike count, and loaded chunks. |
/lagcheck alerts [on|off] |
Enables or disables personal TPS notifications. |
/lagcheck reset |
Clears the heat map, tick history, and chunk-load counters. |
/lagcheck reload |
Reloads the configuration without restarting the server. |

Permissions
| Permission | Description |
|---|---|
checklags.use |
Access to diagnostic commands (top, watch, inspect, region, stats). Default: OP. |
checklags.admin |
Access to reset and reload. Default: OP. |
checklags.alerts |
Receives TPS drop and recovery notifications. Default: OP. |
Staff members who only need to investigate performance issues can be given checklags.use without receiving permission to reset diagnostic data or change the configuration.
The alerts preference commands and help are available without additional permission requirements.
Configuration
The configuration file is located at:
plugins/CheckLags/config.yml
It contains the thresholds, scan intervals, and scoring weights used by CheckLags.
The following settings are the ones you're most likely to adjust:
spike-threshold-ms: 50
tps-alert-threshold: 18.0
census-interval-ticks: 40
heat-decay: 0.9
weights:
block-entity: 2.0
hostile-mob: 1.0
item: 0.5
chunk-load: 8.0
A few examples of how to tune the weights:
- Increase
block-entityif your server has a lot of redstone, hoppers, or other block-entity activity. - Increase
itemif dropped items are a common problem. - Adjust
hostile-mobif mob-heavy areas are contributing to lag. chunk-loadhas a deliberately high default weight to make frequent chunk-loading activity easier to spot.
The best values depend on your server and the type of activity causing its performance problems.
Important notes
There are a few things worth keeping in mind when using CheckLags:
- Chunk heat is relative. It helps identify areas worth investigating, but it doesn't replace a spark profiler when you need detailed timings.
- Entity classification excludes players. Pets and farm animals also have lower weights than hostile mobs.
- Scanning pauses during manual tick control. Detection and scanning are disabled while
/tick freeze,/tick step,/tick sprint, or a custom tick rate is active. These conditions can distort normal tick measurements. - Chunk-load activity uses a rolling 60-second window. Chunks with frequent loading activity will receive a higher score.
- Paper-family servers only. Bukkit and Spigot are not supported because CheckLags relies on Paper API features and its API version requirements.
You can check /lagcheck stats to see whether scanning is currently paused and which statistics source is active.
Feedback and issues
CheckLags is developed by Mr_Nova_76.
If you find a bug or have an idea for a new feature, feel free to get in touch with me on Discord: Mr_Nova_76.
Feedback and suggestions are always welcome.
If you find CheckLags useful, consider leaving a follow or sharing it with other server owners. It really helps the project!


