How to Fix “Unsupported API Version” for a Minecraft Plugin

Direct answer

The plugin declares an api-version newer than your server accepts. Update the server to a supported version or install a plugin release that explicitly supports your current server version.

Diagnosis to use: Bukkit/Paper api-version is a minimum target API declaration; a server older than the declared version will refuse the plugin.

Why the server refuses it

Paper documents that servers older than the version declared in api-version refuse to load the plugin. Modern plugin API versions can include the minor version, so even nearby Minecraft releases may matter.

What to collect: Find the rejected api-version value in the error and compare it with the server startup version. Current Paper metadata may include minor releases where supported.

Do not edit api-version inside the JAR

Changing metadata does not backport code.

A plugin compiled against newer APIs may call classes, methods, registries, or behavior that do not exist on the old server. Editing plugin.yml only removes the warning gate; it does not make the code compatible.

Choose the safe direction

If possible, update Paper after backing up and checking every important plugin.
If you must stay on the current Minecraft version, download the plugin’s documented compatible release.
If no compatible release exists, replace the plugin rather than forcing it to load.

Targeted repair: Use an older compatible plugin release or update the server after backing up and checking all plugins. Do not hand-edit the declaration to trick the server into loading code compiled for newer APIs.

Verify after the change: Restart staging, check plugin startup for API/linkage errors, and exercise the plugin’s main feature.

Check Java too

If the plugin instead throws UnsupportedClassVersionError, that is a Java runtime mismatch, which is a separate problem from Paper api-version.

Official references

These references were checked while preparing this fix. Version-specific behavior can change, so use the project documentation for your exact release when a detail differs.

Was this article helpful?

Help us improve this article

Tell us what is missing, unclear, outdated, or incorrect. You can also suggest something we should add.