Skip to content

Minecraft "Plugin Not Compatible With This Version": Every Rejection Explained

Paper rejects out-of-version plugins with five different messages, and they do not mean the same thing. What each one checks, and which one is harmless.

Updated August 19, 2026
Minecraft

A plugin that is not built for your Minecraft version can fail in five distinct ways, and Paper prints a different message for each. They are not interchangeable. One of them is a hard refusal at load, one is a warning you can ignore, and one is not a version problem at all — it is the plugin's own code breaking on an API that moved.

This page quotes each message as the server actually emits it and explains what was checked. For the broader question of reading a log, see Reading Minecraft Server Logs and Crash Reports; for installing plugins in the first place, How to install plugins for Minecraft Java Edition.

The One Field That Decides This

Every Bukkit-family plugin ships a plugin.yml, and one key in it drives all the version checking:

name: ExamplePlugin
version: 4.1.0
main: com.example.plugin.ExamplePlugin
api-version: '1.21'
plugins/ExamplePlugin.jar → plugin.yml

api-version is the plugin author's declaration of which Bukkit API generation the plugin was written against. The server does not read the plugin's code to work this out — it takes the author's word from this one line, then decides whether to load it. Paper plugins use paper-plugin.yml instead, with the same field.

The server recognises a fixed set of thresholds, each named after the change that made it a boundary:

Constant Version string Why it is a boundary
NONE none No api-version declared at all
FLATTENING 1.13 The block-id flattening — the oldest API the server still accepts
FIELD_NAME_PARITY 1.20.5 Item and component field renames
ABSTRACT_COW 1.21.5 Entity class hierarchy change
ABSTRACT_CUBE_MOB 26.2 The current generation

A plugin declaring anything in that range loads. Anything outside it does not.

The Five Messages

1. Unsupported API version

Could not load plugin 'ExamplePlugin.jar' in folder 'plugins'
org.bukkit.plugin.InvalidPluginException: Unsupported API version 1.22
Console output

The plugin declared an api-version newer than the server provides. This is a plugin built for a Minecraft version you are not running yet. There is no server-side fix: get the build for your version, or move the server forward. Updating Your Minecraft Server covers the second option safely.

2. Plugin API version … is lower than the minimum allowed version

Could not load plugin 'OldPlugin.jar' in folder 'plugins'
org.bukkit.plugin.InvalidPluginException: Plugin API version 1.12 is lower than the minimum allowed version. Please update or replace it.
Console output

The opposite end. The plugin is too old — it declares an API generation from before the flattening. Paper will not attempt to run it, and the message tells you the only two options it has: update the plugin or replace it with something maintained.

This is the message most often misread as "my server is broken". It is not. It is a plugin from 2018 meeting a server from 2026.

3. Legacy plugin … does not specify an api-version

Legacy plugin ExamplePlugin does not specify an api-version.
Console output

This one is a warning, and the plugin still loads. No api-version key means the plugin predates the field, so the server runs it through a legacy compatibility layer that rewrites old material and enum names on the fly. It usually works. It is also a strong signal that the plugin is unmaintained, and it is the first thing to remove when you are bisecting an unexplained failure.

4. API version string should be of format …

API version string should be of format "major.minor.patch" or "major.minor", where "major", "minor" and "patch" are numbers. For example "1.18.2" or "1.13", but got 'latest' instead.
Console output

The api-version value is not a version number. Almost always a hand-edited plugin.yml — a jar was unpacked, the field changed to latest or 1.21.x or left unquoted so YAML read it as a number, and repacked. Restore the original jar. Fixing YAML and JSON Config Errors on a Minecraft Server covers the unquoted-version trap, which bites here more than anywhere else.

5. Error occurred while enabling … (Is it up to date?)

Error occurred while enabling ExamplePlugin v4.1.0 (Is it up to date?)
java.lang.NoSuchMethodError: 'org.bukkit.inventory.ItemStack org.bukkit.inventory.ItemStack.clone()'
Console output

The most-seen and least-understood of the five. The version check passed. The plugin declared a supported api-version, loaded, and then threw while starting — because it calls an API method that no longer exists in the shape it expects.

The parenthetical question is Bukkit's own guess, and it is usually right. What confirms it is the exception type:

Exception What it means
java.lang.NoSuchMethodError The method still exists by name but its signature changed
java.lang.NoSuchFieldError A field was renamed or removed
java.lang.NoClassDefFoundError on an org.bukkit class A whole class moved or was deleted
java.lang.NoClassDefFoundError on a third-party class A missing dependency, not a version problem — see below

Paper prints the same wording for each phase it runs a plugin through, so you may also see Error occurred (in the plugin loader) while enabling …, … while disabling …, … while unregistering events for … and several more. They all mean the plugin threw during that phase.

NoSuchMethodError is not something you can configure your way out of

It is a compiled-in reference to a method that is not there. No config change, no restart and no flag will resolve it. The plugin needs a build made against your server's API generation.

The Rejections That Are Not About Versions

Four more messages come from the same part of startup and are frequently blamed on version mismatch. They are not.

plugins/ExamplePlugin.jar is not a jar file, cannot load a plugin from it!
plugins/paper-26.2.jar appears to be a server jar! Server jars do not belong in the plugin folder.
plugins/Example.jar does not contain a plugin.yml! Could not determine plugin type, cannot load a plugin from it!
org.bukkit.plugin.UnknownDependencyException: Unknown/missing dependency plugins: [Vault]. Please download and install these plugins to run 'ExamplePlugin'.
Console output

In order: a renamed or partially uploaded file; a server jar dropped into plugins/; a library or mod jar rather than a plugin; and a plugin whose declared dependency is not installed. The last is the common one — Vault, ProtocolLib and PlaceholderAPI account for most of them, and the message names both the missing plugin and the one that wanted it.

Two more you may hit on a large plugin set:

Ambiguous plugin name 'Essentials' for files 'plugins/EssentialsX-2.20.jar' and 'plugins/EssentialsX-2.21.jar' in 'plugins'
[SimpleProviderStorage] Circular plugin loading detected!
[SimpleProviderStorage] Circular load order: PluginA -> PluginB -> PluginC -> PluginA
Console output

The first is two copies of the same plugin — delete the old jar rather than renaming it, because the loader reads any .jar in the folder. The second is a genuine dependency loop, and Paper names the plugins in it so you can report it to their authors.

Telling This Apart From a Java Version Problem

One error looks like a plugin version failure and is not:

java.lang.UnsupportedClassVersionError: com/example/plugin/ExamplePlugin has been compiled by a more recent version of the Java Runtime (class file version 69.0), this version of the Java Runtime only recognizes class file versions up to 65.0
Console output

This is the JVM refusing the plugin's bytecode, before Bukkit's version check runs at all. It says the plugin was compiled for a newer Java than your server runs. The class name at the front tells you who: anything under com.example is the plugin, and the fix is either a plugin build for your Java or a higher Java version on the Startup tab. Reading Minecraft Server Logs and Crash Reports carries the full class-file-version table.

Mods Are a Separate System

None of this applies to Fabric, Forge or NeoForge. Mods do not have api-version, do not go in plugins/, and produce entirely different failures — Fabric's Incompatible mods found! block, or a Mixin refusing to apply. Minecraft Server Software Compared covers which frameworks take which, and How to install mods for Minecraft Java Edition covers the mod side.

A server running Paper cannot load mods, and a server running Fabric cannot load plugins, no matter what either file says about versions.

Made with 💜 by GameServerKings

Need a Minecraft server?

Deploy an instantly-provisioned Minecraft server on high-clock hardware — DDoS protected, no contracts, cancel anytime.

From $4.80 /month

Deploy a server Minecraft server hosting