Plugin version numbers are a rough guide, not a contract. Whether a plugin works depends on which parts of the server it touches, and a small plugin from four years ago is often more reliable than a large one from last month.
What api-version declares
Every plugin ships a plugin.yml, and inside it a line saying which server API generation it was written against. The server reads that and decides how to treat the plugin — including whether to apply legacy conversion for old material and block names. A plugin with no api-version at all is treated as pre-1.13, which is why very old plugins sometimes behave strangely rather than simply failing.
What makes a plugin fragile across versions
| Uses | Survives version changes? |
|---|---|
| Only the standard server API | Usually yes, for years. |
| NMS or internal server classes | No. These are rewritten between versions. |
| Packet manipulation | Rarely. Protocol changes break it. |
| Material and block names | Mostly, but renames do happen. |
| Chat and component handling | Fragile since chat signing arrived. |
Judging a plugin before you trust it
- Read the plugin's own compatibility note
A well-maintained plugin says which versions it supports. That statement is worth more than the version number in the filename.
- Look at what it does
A plugin that renames chat prefixes touches little. A plugin that adds custom entities touches everything. Guess accordingly.
- Test it on a copy first
«Loads without error» is not the same as «works». Load it, then use the feature you installed it for.
- Watch the console for deprecation warnings
The server tells you when a plugin is using an old API. That is a warning about the future, not an error today — but it names your next migration.
A plugin can start cleanly and then throw an error the first time a specific feature runs, which might be a week later when a player triggers it. The console at startup is a weak test; using every feature once is a real one.
«Supports 1.20–1.21» is a maintained project. A download page that only says «Minecraft 1.16» and was last touched in 2021 is a project you will be maintaining yourself, whether you planned to or not.