Minecraft Plugin Failed to Load — Fix "Could Not Load" Errors
Six distinct reasons a Paper, Purpur or Spigot plugin refuses to load — from corrupted jars to version-breaking API changes — and the exact fix for each, read straight from the log.
The real error is above the summary line
Open logs/latest.log and search for the plugin's name. "Could not load" or "failed to load" is usually just a wrapper message — the actual Java exception explaining why is printed in the lines right above or below it.
Match that exception against the six causes below. This isn't limited to pure Paper/Spigot servers — a hybrid loader like Mohist lets modpacks such as RLCraft run Bukkit plugins alongside Forge mods, and the same load-failure patterns apply there too.
"Could not load 'plugins/X.jar' in folder 'plugins'"
Server startup log shows this exact line, usually followed by a Java stack trace, and the plugin never appears in /plugins.
The jar file itself is corrupted, incomplete (a partial download), or isn't actually a valid plugin jar (missing plugin.yml inside it).
Re-download the plugin from its original source (Modrinth, SpigotMC, Hangar) — a half-finished upload transfer is the most common cause. Check the file size matches what the download page shows. If it's a plugin you built or edited yourself, verify plugin.yml is present at the jar's root, not nested in a subfolder.
"Plugin X requires Y which is not loaded" (unknown/missing dependency)
Log explicitly names a required plugin or API that isn't present — most commonly ProtocolLib, Vault, PlaceholderAPI, or Paper itself when running on Spigot.
The plugin has a hard dependency declared in its plugin.yml that your server doesn't have installed, or the dependency failed to load itself (check further up the log — a cascading failure often starts with one plugin, not the one reporting the error).
Install the named dependency plugin first, in the same plugins/ folder, then restart. If the dependency is already installed but still reported missing, check load order isn't the issue — soft dependencies load if present but don't error if missing; hard dependencies (depend: in plugin.yml) must load successfully first.
java.lang.NoClassDefFoundError or ClassNotFoundException
Stack trace names a specific Java class that couldn't be found, often from a library the plugin bundles or depends on (e.g. a specific JSON or database driver library).
The plugin was built expecting a library (shaded/bundled dependency, or a server-provided API) that either isn't present on your server version, or the plugin's jar was built incorrectly and the library wasn't bundled in (a packaging mistake by the plugin author, more common on very new or rarely-updated plugins).
Check the plugin's page for a minimum server version or required library plugin. If the plugin is unmaintained and this is a packaging bug, there's often a GitHub issue already describing it — search the exact class name from the error. As a last resort, try an older release of the same plugin; packaging regressions get fixed and un-fixed across versions.
java.lang.NoSuchMethodError after a Minecraft or server-software update
Plugin loaded fine before you updated Minecraft or switched Paper/Spigot versions; now it fails with NoSuchMethodError referencing a Bukkit/Paper API method.
The plugin calls an API method that was removed, renamed, or changed signature in the Minecraft version you're now running. This is a version-compatibility break, not a bug in your setup — it means the plugin hasn't been updated for your server version yet.
Check the plugin's page for the newest version explicitly supporting your Minecraft version — plugin authors usually publish an update within days to weeks of a major MC release. If none exists yet, you have three options: wait for the update, downgrade your server to the last version the plugin supported, or (for popular plugins) check if a community fork already patched it.
Plugin loads, but throws an exception the moment it tries to enable
Log shows "Loading X v1.0" followed immediately by an exception (often inside onEnable()), rather than the plugin failing to load at all. The plugin shows as present but non-functional.
Almost always a corrupted or outdated config.yml for that specific plugin — the plugin's code expects a config key that an old config file doesn't have, and the resulting null value crashes onEnable(). Common after a plugin update that added new config options.
Stop the server, rename (don't delete) the plugin's folder under plugins/<PluginName>/config.yml to something like config.yml.bak, and restart — the plugin will regenerate a fresh default config. Then re-apply your customizations into the new file by hand, checking for renamed or new keys. This loses custom settings but almost always fixes the crash.
Two plugins both claim the same command or listener and one refuses to load
No crash, but one of two similar plugins silently doesn't register — commands from it don't work, and there's a quiet warning (easy to miss) about an overridden command in the log.
Two plugins register the same command name (e.g. two different "warp" or "kit" plugins) or the same event priority slot. Bukkit resolves this by load order, not an error — whichever loads second usually wins or loses depending on the specific conflict type.
Identify the overlap — usually two plugins doing similar things (two economy plugins, two warp plugins). Pick one and fully remove the other; running both "just in case" is what causes the silent conflict. If you need features from both, check whether one has an add-on/expansion for the other instead of running two competing cores.
FAQ
Why does my plugin show "failed to load" with no further explanation?+
Scroll up in the log — the real error is usually printed just above the generic "failed to load" summary line, often as a full Java stack trace. The summary line is just Bukkit/Paper's wrapper message; the actual cause (missing dependency, corrupted jar, version mismatch) is in the detail above it.
Do all plugins need to match my exact Minecraft version?+
Not always — many plugins declare a range of supported versions and work fine across several Minecraft releases without updates, especially if they don't touch APIs that changed. But after a major Minecraft version bump (e.g. 1.20 → 1.21), expect some plugins to need an update before they'll load cleanly again.
Can a bad plugin crash my whole Minecraft server, not just fail to load?+
Yes — a plugin failing to load during startup usually just disables that one plugin and the server continues. But a plugin that loads successfully and then throws an unhandled exception during normal play (a ConcurrentModificationException, an infinite loop in an event handler) can crash the entire server. See the general crash-fix guide if your server is crashing after startup, not just failing to load a specific plugin.
How do I know which plugin is causing a startup error if the log doesn't name it clearly?+
Bisect: move half your plugins out of the plugins/ folder into a temporary folder, restart, and see if the error persists. Repeat with half of the remaining set until you isolate the one plugin responsible. With 8 plugins this takes about 3 restarts.
Is it safe to just delete a plugin's config.yml to fix a load error?+
Yes, as a diagnostic step — rename it rather than delete, restart to let the plugin regenerate a fresh default config, confirm that fixes the crash, then manually re-apply your old settings into the new file. Keep the renamed old file around until you've confirmed the new one works, in case you need to reference old values.
One-click plugin install from Hangar
CoalHost installs Paper/Purpur plugins directly from Hangar with dependency warnings shown up front, and our crash agent reads plugin load errors for you. From €10.69/month.
View Minecraft Hosting →