API versioning
Why a plugin refuses to load, and what the numbers in `api` mean.
Every server build exposes an API version, and every plugin declares which ones it was written against. The server compares them at load time and refuses anything that does not match, instead of loading it and crashing later in the middle of a game.
The format
MAJOR.MINOR.PATCH, and each part means something specific:
- MAJOR changes when something breaks. Classes disappear, method signatures change, behaviour you relied on is gone.
- MINOR changes when something is added. Existing code keeps working.
- PATCH changes for fixes that touch neither.
The compatibility rule
A plugin declaring api: [5.0.0] loads on a server whose API version is:
- the same MAJOR, and
- a MINOR equal to or higher than the plugin's.
| Plugin declares | Server runs | Loads |
|---|---|---|
5.0.0 | 5.4.2 | Yes |
5.4.0 | 5.0.0 | No, the plugin may use something that did not exist yet |
4.9.0 | 5.0.0 | No, different major line |
Declare the oldest version you actually support, not the one you happen to be running:
api: [5.0.0]Multiple entries mean multiple major lines:
api: [4.0.0, 5.0.0]Only declare multiple major lines if you have tested both. It is a claim, not a wish.
"Incompatible API version"
The server prints this and skips the plugin. It means exactly one thing: the plugin was built for a different API line than the server is running. It is not a bug in either.
Look for a newer build
Check the plugin's repository for a release against your server's API version.
Accept the answer if there is none
The plugin is unmaintained or has not caught up. Nothing on the server side changes that.
Do not fake the manifest
Editing api in plugin.yml gets past the check and into a crash that is much harder to read than
the refusal was.
Finding your server's API version
versionIt prints the server version and the API version alongside it. That number is what a plugin has to be compatible with.
As a plugin author
Bump your own version when you release. Update api only after testing against the new line: a
major server release usually needs real changes, not a number edit. The
changelogs list what moved.