Mod Doctor
- By
Names the mod behind your server's crashes, writes a plain crash report, and can switch a mod off for the next restart.
Mod Doctor
Names the mod behind your server's crashes and exceptions, writes a plain crash report, and can switch a mod off for the next restart. Also audits new servers for common setup mistakes. Server-side only.
What it does
- Exceptions by mod. It watches every error the server logs and groups them by the mod that caused them, using the stack trace. One bug firing a thousand times is one line.
- Plugins that failed. On boot and on
/doctorit lists every plugin that should be running and is not, with the server's reason. - Crash reports. After a crash it writes
mod-doctor-crash-<time>.txtbeside the server, naming the likely culprit and how sure it is, with the stack and the last log lines. The next boot prints it. - Switch a mod off.
/doctor disable <mod>takes a mod out for the next restart, and/doctor enable <mod>undoes it. It warns before removing a mod others depend on, never overwrites a file and never deletes one. - Setup audit.
/servercheckprints a PASS or WARN line for each common mistake.
How a crash is caught
| What happened | What Mod Doctor does |
|---|---|
A plugin fails while loading, and the server stops with mod_error |
Writes the report on the way out and names that plugin |
| A world crashes | Writes the report two seconds later, whether the world recovers or not |
| The server stops with any other bad reason | Writes the report on the way out |
| The process dies with no warning (killed, power lost, JVM crash) | Writes the report at the next boot from what it saved during the run, and reads any hs_err_pid file |
A sudden death is never reported above medium confidence. An exception on its own does not end a process, so the last one is a lead, not proof.
Commands
Operators and the console only.
| Command | What it does |
|---|---|
/doctor |
Mods not running, exceptions by mod, duplicate ids, last crash report |
/doctor disable <mod> [force] |
Switch a mod off from the next restart. <mod> is a plugin name, Group:Name or the jar file name. force skips the warning about mods that need it |
/doctor enable <mod> |
Undo that |
/servercheck |
The setup audit. /doctor check does the same |
What /servercheck looks at
Whitelist or password, age of the newest backup (the server's own backups, Server Backup, or a folder you name), operator count, permissions.json (valid, and no ordinary group holding *), loaded worlds and their config files, free disk space, server version against the newest the server knows of, sign-in mode, and heap size. It reads and reports. It changes nothing.
Settings
moddoctor.properties in the mod's data directory (created on first start):
| Key | Default | Meaning |
|---|---|---|
keepReports |
20 |
Crash reports to keep; older ones are removed |
logTailLines |
40 |
Log lines copied into a report |
maxBackupAgeHours |
48 |
/servercheck warns when the newest backup is older |
maxOperators |
5 |
/servercheck warns above this |
minHeapMb |
4096 |
/servercheck warns below this |
extraBackupFolder |
empty | Another folder to look in for backups |
Mod Doctor and Mod Compat Guard
Mod Compat Guard predicts: it reads manifests and bytecode and says what will fail. Mod Doctor reports what did fail, while the server ran. Mod Doctor repeats none of Guard's checks. If Guard is installed, /doctor shows its error count and crash reports include its errors, so the two work well together.
Limits
- A duplicate plugin id or a dependency loop stops the server before any mod runs, so Mod Doctor cannot report in that boot.
/doctordoes warn if a second copy appears while the server is running. For a server that will not start, use Mod Compat Guard's standalone command. - A mod in a stack trace is evidence, not a verdict. A mod can be blamed for a crash that started in another mod or in the server.
- On Windows a loaded jar cannot be moved.
/doctor disablethen switches the mod off inconfig.json, and the file moves tomods-disabledat the next start. This path is tested on a real server. The direct move used on Linux is tested only in unit tests, not on a live Linux server. - Reading an
hs_err_pidfile is tested only in unit tests. No real JVM crash file has been through it.
Tested on server 0.7.5 with real failures from a throwaway test mod: a world crash, a failed setup(), a missing dependency, a shutdown with reason crash and a killed process. It also ran alongside 34 other mods with no exceptions. On 0.8.0-pre.3 it compiles, passes Update-Ready Check and loads, but only in bare mode without game assets.
Install: drop the jar into the server's mods/ folder and restart. Licence: MIT.
Not affiliated with, endorsed by or connected to Hypixel Studios.
Need something custom? I build small server plugins to order from $35 (fixes) and $90 (a new one-feature plugin): https://ko-fi.com/molonlav3/commissions . If this mod saved you time, a coffee helps keep the updates coming: https://ko-fi.com/molonlav3
Updating Hytale? See which mods work with Update 8: https://playerbase-servers.molonlav3.workers.dev/update-8
Mod Doctor Team
