PerlandFailure catalogue

A plugin's file could not be loaded

Errorplugin_load_failed

The server or proxy found a plugin jar it could not read or load, so it skipped that plugin while the rest of the server started.

What the log shows

Written example5 lines
[17:05:12 INFO]: [bootstrap] Loading Paper 1.20.4-499-ver/1.20.4@a8b2c3d for Minecraft 1.20.4
[17:05:15 ERROR]: [ModernPluginLoadingStrategy] Could not load plugin 'HomeWarps-3.2.jar' in folder 'plugins'
org.bukkit.plugin.InvalidPluginException: Unsupported API version 1.21
    at org.bukkit.craftbukkit.v1_20_R3.util.CraftMagicNumbers.checkSupported(CraftMagicNumbers.java:412) ~[paper-1.20.4.jar:git-Paper-499]
    at io.papermc.paper.plugin.provider.type.spigot.SpigotPluginProvider.createInstance(SpigotPluginProvider.java:121) ~[paper-1.20.4.jar:git-Paper-499]

Your log will have other names, versions and times. Search a line of it from all failures.

What it means

Before a plugin can run, the server opens its jar, reads its description file (plugin.yml or paper-plugin.yml on Paper and Spigot, velocity-plugin.json on Velocity, plugin.yml or bungee.yml on BungeeCord and Waterfall) and loads its main class. When one of these steps fails, the server prints a load error and skips the plugin.

The server itself keeps starting. Only that plugin is missing, along with any plugin that depends on it.

Why it happens

  • The jar is damaged or incomplete. A download that was cut short, or a file that is not a jar at all (a web page saved as .jar).
  • The plugin is for another kind of server. A Velocity or BungeeCord plugin in a Paper server’s plugins folder, a Paper plugin on a proxy, or a Forge or Fabric mod placed in plugins.
  • The plugin is built for a newer Minecraft version. Its api-version is newer than the server, which Paper and Spigot refuse with Unsupported API version.
  • The description file is broken. An invalid plugin.yml, a main class that does not exist, or an invalid plugin id on Velocity.
  • The plugin needs a newer Java (proxies). On Velocity, BungeeCord and Waterfall, a plugin compiled for a newer Java than the proxy runs is reported here. On Paper and Spigot the same problem has its own issue, java_version_mismatch.

How to fix

  1. Note the file the error names and read the exception under it: it usually says which step failed.
  2. Download the plugin again from its official page. Pick the build for your server software (Paper, Spigot, Velocity, BungeeCord) and your Minecraft version.
  3. Replace the jar in the plugins folder and restart the server.
  4. If the error says Unsupported API version, use an older build of the plugin made for your Minecraft version, or update the server. Updating the Minecraft version changes the world, so take a backup first.
  5. If the file is a mod, not a plugin, remove it from plugins: mods need a Forge, NeoForge or Fabric server.
  6. If you edited the plugin’s description file yourself, check plugin.yml with a YAML validator.

In Perland

The issue appears in the server’s Diagnosis tab with the plugin’s file name. Plugin Studio installs plugins in a build that matches the server’s platform and Minecraft version, and can update or remove the one that failed. You can also replace or delete the jar in the plugins folder from the Files tab, then restart the server.

References

Details the diagnosis reports

Perland's server diagnosis returns this failure as the code plugin_load_failed with these parameters, each present only when the log names it.

ParameterMeaning
pluginThe plugin's jar file name without `.jar`, or its id on Velocity. Absent when the line names no file, as on Paper 1.21 for a plugin.yml that does not parse.

Log lines this page covers

  • Could not load 'plugins/....jar' in folder 'plugins'
  • Could not load plugin '....jar' in folder 'plugins'
  • Could not load 'plugins/....jar' in 'plugins'
  • Error loading plugin: Directory 'plugins/....jar' failed to load!
  • Error loading plugin: Invalid plugin.yml
  • Unable to load plugin plugins/....jar
  • Can't create module for plugin ...
  • Could not load plugin from file plugins/....jar
  • Error loading plugin ...