LagDoctor

Lag Doctor

Lag Doctor helps Paper server owners turn a slowdown into measurements and next steps. Created by William Liu (@starchlorddotcom). Free and MIT licensed.

Choose your version

• Paper 26.3 / Java 25+: Lag Doctor 0.3.0 Beta
• Paper 1.21.11 / Java 21+: Lag Doctor 0.2.0 Beta

Use the matching build. Other Minecraft versions, Spigot and Folia are not supported. Paper 26.3 itself is currently beta.

Features

• Tick durations: mean, worst per-window p95, maximum and slow-tick percentage.
• Healthy/slow evidence comparisons using GC counters, chunk activity and entity counts.
• Optional bounded scans of already-loaded entity chunks.
• Incident history and recovery detection.
• Before/after comparisons that flag changed workloads.
• Offline HTML/text exports; world names and coordinates are omitted by default.

Install

Stop the server, remove any older LagDoctor JAR from plugins/, install the matching JAR above, and restart with the required Java version. Keep your existing LagDoctor configuration. Wait about a minute, then run /ld report as an operator or from the console. Permission: lagdoctor.admin. Test on a disposable compatible server or backed-up copy first; do not downgrade an existing world.

Commands

• /ld report — recent tick performance and diagnostic evidence
• /ld baseline — save measurements before a change
• /ld compare — compare with newer measurements
• /ld scan and /ld scan stop — start or cancel an entity scan
• /ld hotspots — inspect scan results
• /ld incidents — review incident history
• /ld export — save offline HTML and text reports

Beta status

Developed with substantial AI assistance. All 18 automated tests pass; local smoke tests cover Paper 26.3 build 143 for 0.3.0 and Paper 1.21.11 build 132 for 0.2.0. Large-server overhead and player-client interactions are not validated. Counts and associations do not prove CPU cost or causation. Lag Doctor complements spark and does not identify a guilty plugin or player. It does not fix lag automatically.

No telemetry, account requirement, subscription or automatic world changes. /ld export locations explicitly includes scan locations; review reports before sharing.

Feedback and source

Report a bug or share testing feedback. Include the LagDoctor, Paper and Java versions, approximate player count, scenario and whether the report helped.

Complete 0.3.0 source, tests, documentation and example reports. Older 0.2.0 source. Minecraft and Paper are separate projects and are not bundled.