# A plugin's file could not be loaded

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.

- Code: `plugin_load_failed`
- Severity: error
- Category: Plugins
- Server types: Paper, Spigot, Bukkit, Velocity, BungeeCord, Waterfall
- Page: https://failures.perland.online/failures/plugin_load_failed/

## Example log

```text
[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]
```

## Parameters

| Parameter | Meaning |
| --- | --- |
| `plugin` | The 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 ...`

## 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

- [Paper documentation: adding plugins](https://docs.papermc.io/paper/adding-plugins)
- [Paper documentation: plugin.yml](https://docs.papermc.io/paper/dev/plugin-yml)
- [Velocity documentation](https://docs.papermc.io/velocity)