Plugin not loading or "Unsupported API version" error

When a plugin will not load, Paper always prints the reason in the console during startup. Restart the server, scroll to the line that mentions the plugin's file name, and match the error to one of the causes below.

Find the error

Restart the server and watch the console, or open logs/latest.log in the file manager after startup.
Search for Could not load or the plugin's name.
Read the first line of the error and the Caused by: lines below it. Those tell you what actually went wrong.

"Unsupported API version"

Could not load 'plugins/CoolPlugin.jar' in folder 'plugins'
org.bukkit.plugin.InvalidPluginException: Unsupported API version 1.21

The plugin declares in its plugin.yml that it needs a newer server API than you are running. In this example the plugin was built for 1.21, but the server is older.

Fix it by either:

downloading an older release of the plugin that supports your Minecraft version, or
updating your server to the Minecraft version the plugin targets.

Editing the plugin's plugin.yml to lower the version is not a real fix. The plugin will usually crash later when it calls methods that do not exist on your server.

Missing dependency

Unknown/missing dependency plugins: [Vault]

The plugin requires another plugin. Install the one named in the brackets, then restart. Check that the dependency also supports your Minecraft version.

Built for the wrong platform

If the error mentions plugin.yml not found, or Invalid plugin.yml, the file is probably not a Bukkit plugin at all. Common mix-ups:

A Forge or Fabric mod placed in plugins. Mods do not work on Paper.
A BungeeCord or Velocity plugin placed on a game server. Proxy plugins go on the proxy.
A source code zip or a zip containing the jar. Extract it and upload only the .jar.

Java version errors

java.lang.UnsupportedClassVersionError: ... class file version 65.0

The plugin was compiled for a newer Java than your server runs. See Java version mismatch errors.

NoSuchMethodError or NoClassDefFoundError

These mean the plugin loaded but called code that is not there. Usually the plugin is too old or too new for your server, or a dependency (such as ProtocolLib) is the wrong version. Update the plugin and its dependencies to builds made for your Minecraft version.

Ambiguous plugin name

Ambiguous plugin name 'Essentials'

Two jars with the same plugin name are in plugins, often an old and a new version. Delete the old one.

Plugin loads but is disabled

If you see Disabling PluginName right after it enables, the plugin turned itself off. Scroll up for its own message. Common reasons are an invalid config.yml, a database it cannot reach, or a missing optional dependency. For config errors, see configuring plugins. For database errors, see plugins that need MySQL.

Still stuck?

Share the full error (from Could not load down to the last Caused by) in the Schokr Discord.