Mod Compat Guard
- By
Checks every mod on your server at boot and reports which ones will fail and why: duplicates, missing dependencies and calls to server code that no longer exists.
Mod Compat Guard
Checks every mod on your server and tells you which ones will fail, and why, before you lose an evening to a boot loop. Server-side only.
What it checks
| Check | Code in the report | What the server does about it |
|---|---|---|
| Two files with the same plugin id, such as two versions of one mod | duplicate-id |
Stops with MOD_ERROR. The report names the older file |
manifest.json missing or unreadable |
bad-manifest |
Skips the file |
| Required dependency missing or the wrong version | dependency |
Drops that plugin. Anything that needs it fails too, and the report follows the chain |
| Dependency loop | dependency-cycle |
Cannot work out a load order |
Main class missing, or without the public JavaPluginInit constructor |
main-class |
Stops with MOD_ERROR |
| The mod calls server code that does not exist on this version | missing-api |
Loads, then crashes with NoSuchMethodError or NoClassDefFoundError when that code runs |
ServerVersion excludes the running server |
server-version |
Warns and loads it anyway |
No ServerVersion |
no-server-version |
Warns; the server says this will become a hard error |
| Optional dependency missing | optional-dependency |
Nothing; shown as a note |
The manifest checks use the server's own decoder and version rules, so a mod passes or fails here as it does on the server. missing-api is the part version numbers cannot tell you: it reads each mod's bytecode and looks up every class, method and field the mod uses in the classes of the server that is actually running, including inherited members.
Mods switched off in the server config, or by DisabledByDefault, are counted and skipped.
Using it
The report goes to the server log at every start and to report.txt in the mod's data directory.
/modcheck scans again and prints the report (operators and the console). It shows the first 20 findings; the rest are in report.txt. It never moves files.
When the server will not start
The scan runs while plugins are being constructed, before setup(), so the report can still reach the log in a boot that is about to stop on a duplicate id or a broken mod. A failure that comes earlier, such as a dependency loop, stops the server before any mod runs. For those, use the standalone check with the server stopped:
java -jar mods/mod-compat-guard-1.0.0.jar --mods modsThat form works when HytaleServer.jar sits in the folder above mods, or in Server/ there. Options: --mods <folder>, --strict, --no-bytecode, --move-failing. It checks against whichever server jar is on the class path, so you can point it at a new server jar before you update.
Settings
modcompatguard.properties in the mod's data directory (created on first start):
| Key | Default | Meaning |
|---|---|---|
bytecodeCheck |
true |
Run the missing-api and main-class checks |
strictServerVersion |
false |
Treat a ServerVersion that excludes the server as an error |
moveFailing |
false |
Move files with errors to mods-disabled/ beside the mods folder |
With moveFailing=true, files with errors move out on the next start. On Windows a loaded jar cannot be moved, so the report says NOT MOVED and points to the standalone check. If more than half of the files fail, nothing moves. Read the report before you turn this on: a mod with one missing call may still mostly work.
Limits
ServerVersionon a pre-release: ranges such as0.xdo not match0.8.0-pre.3. If the range covers the plain release, the report shows a note instead of a warning.missing-apicovers server classes only. It does not check calls from one mod into another.- Asset contents are not checked, only pack manifests.
Install: drop the jar into the server's mods/ folder and restart. Licence: MIT.
Need something custom? I build small server plugins to order from $15 (fixes) and $29 (a new one-feature plugin): actuallyop.com/services. More free tools: actuallyop.com.
Mod Compat Guard Team
