PAPER PLUGIN TROUBLESHOOTING
Fix a Paper plugin that will not load
Follow a reliable diagnostic order for a missing, disabled, or erroring Minecraft Paper plugin.
Start with the first plugin-specific startup error. Paper’s plugin list and server log help separate a missing JAR from a plugin that was found but failed to enable, and those cases need different fixes. Test changes on a backed-up server copy and restart fully after each change. MCraft AI can help review project files or a sanitized error excerpt, but it cannot inspect or control your live server; any proposed fix still needs suitable build and runtime testing.
Confirm the server type and plugin location
Confirm that this server is actually running Paper and that the plugin release supports your exact Minecraft and server versions. Vanilla, Fabric, Forge, and NeoForge use different extension systems; a plugin JAR is not interchangeable with a mod.
Place the plugin JAR in the plugins folder at the server root, not in a nested folder. Stop and start the server, then run /plugins in game or plugins in the console. If the plugin is missing from the list and startup log, check the server type, working directory, file extension, and folder location first. If it appears in red, Paper found it but did not enable it. Green means it enabled, not that every feature works.
Read the first relevant startup error
Check the console output and logs/latest.log from the same full startup. Find the first warning or error that names the plugin, then read its exception and first Caused by line. Later errors can be consequences of that first failure, so changing several files at once makes the cause harder to identify.
Keep the complete relevant error lines when asking for help, but remove access tokens, passwords, private addresses, player identifiers, and unrelated private log content before sharing them.
Match the plugin to Minecraft, Paper, and Java
Compare the plugin’s published compatibility notes with the exact Minecraft version, Paper build, and Java runtime used by the server. Check the runtime required by that Minecraft release in Paper’s current setup guidance instead of relying on a Java version remembered from an older server.
UnsupportedClassVersionError commonly means the plugin bytecode needs a newer Java runtime than the server uses. NoSuchMethodError or ClassNotFoundException can point to a server API or dependency mismatch. These messages need context: verify the plugin author’s supported versions and the full first exception before choosing an upgrade or another release.
Check required plugins and packaged metadata
An UnknownDependencyException names a required plugin that is missing or unavailable. Read the plugin author’s install notes, add the compatible dependency from its official source, and restart. Do not guess at dependencies based on a similar plugin name.
A plugin JAR needs valid plugin metadata in the expected location. Bukkit-style plugins use plugin.yml; Paper plugins can use paper-plugin.yml with different loading semantics. Check Paper’s documentation before changing descriptors, and rebuild from source if metadata needs correction. A source ZIP, project folder, or ordinary mod JAR is not itself an installable plugin JAR.
Check that the download is a real JAR
Verify that the downloaded file is the plugin artifact for your platform, not a ZIP containing several platform builds, an HTML error page renamed to .jar, or a partial download. Some plugin authors distribute multiple files; follow their instructions to select the Paper or Bukkit-compatible JAR.
If the archive is corrupt or its contents do not match the author’s release, download it again from the official project page. Do not install an unknown JAR on a server with real players or valuable world data.
Isolate the failure on a test copy
Back up the world and server files, then reproduce the issue on a disposable copy. Stop the server before moving the last changed plugin out of the plugins folder. Start once to see whether the error disappears, then add plugins back one at a time, restarting after each change.
Keep existing plugin data and configuration while diagnosing. A green entry in /plugins confirms that the plugin enabled; if its command or feature still fails, inspect that feature’s permission, configuration, dependency, and runtime log separately.
Give a maintainer a useful report
Include the server software and exact build, Minecraft version, Java runtime, plugin name and release, whether it is absent/red/green in /plugins, the first relevant startup error with its Caused by lines, and what changed immediately before the problem. This lets a maintainer distinguish discovery, compatibility, dependency, metadata, and feature-level failures.
For a plugin project in MCraft AI, provide the target Paper and Minecraft versions, Java runtime, relevant descriptor or source files, and sanitized startup excerpt in the project. MCraft can suggest and review code changes; static checks, an optional isolated build, and a real server load are separate steps. Build JAR is disabled unless its runner is configured, and a successful compilation alone does not prove the plugin loads.