Why Some Plugins Break Between Minecraft Versions, and How Server Admins Can Read the Signs
Why Paper plugins that reach into NMS break on new Minecraft versions while API-only plugins survive, how the switch to Mojang mappings changes things on 26.1, and how to tell which plugins are safe before you update.
ChunkPod Team · · 8 min read
Why Some Plugins Break Between Minecraft Versions, and How Server Admins Can Read the Signs
A Paper plugin that ran fine on 1.21.11 can throw errors on startup on 26.1, even though nothing changed in your config. The plugin author didn't necessarily do anything wrong. Minecraft's internals shift between versions, and any plugin that touches those internals has to be rebuilt to match. This post explains what actually changes under the hood, why some plugins survive updates untouched while others don't, and how to spot which kind you have installed.
The two layers a plugin can touch
A Paper plugin talks to your server through one of two layers.
The first is the Bukkit API, which Paper extends and improves. That's the layer that gives you Player, World, Block, event listeners, commands, all the friendly classes you see in most plugin tutorials. This API is deliberately stable. Mojang can rename an internal method or change how the game stores mob AI, and the Bukkit method for teleporting a player still looks and behaves the same.
The second is NMS, which stands for net.minecraft.server. That's the vanilla Minecraft server code itself. Everything Bukkit does eventually goes through it, but plugins are not supposed to call it directly. NMS classes, methods and fields change on every Minecraft version. That's not carelessness on Mojang's part, it's what a live game looks like: new blocks, new packets, new registries, refactors of old systems.
The API layer is where safe plugins live. The NMS layer is where the fragile ones live.
Why plugins reach into NMS at all
The API doesn't cover everything. Some things the game can do, the API has no method for. A plugin that spawns a custom entity type, edits a chunk's raw block data for performance, sends a fake packet to a single player, hooks into the pathfinding of a mob, or replaces a piece of vanilla logic outright can't do that job through Bukkit alone. It has to reach into the server internals.
That's a real trade. NMS gives the plugin power the API doesn't offer, at the cost of tying it to a specific Minecraft version. When 26.1 lands, the class names might have moved, a method might take an extra argument, a field might be private now. The plugin's compiled bytecode still expects the old shape, and the JVM throws NoSuchMethodError or NoClassDefFoundError at startup. That is the classic "plugin worked on 1.21.11, breaks on 26.1" error.
Mojang mappings and the Paper switch
There's a second wrinkle called mappings.
Up to and including 1.21.11, Mojang shipped the game with obfuscated names. A class you might think of as EntityPlayer was actually shipped with a short, meaningless name. To make NMS usable at all, someone had to map those obfuscated names back to human-readable ones. For years, Spigot and Paper used community-maintained Spigot mappings. Plugins were written against those names, and the server "reobfuscated" the plugin at runtime to match the real Minecraft classes.
Paper switched to Mojang's own official mappings by default, starting with 1.20.5. Mojang published those mappings themselves, and using them cut out the reobfuscation step. It was a cleaner setup for plugin authors, and the names lined up with what modders on Fabric and Forge already used.
For admins, the switch mattered in one specific way: older NMS plugins written against Spigot mappings didn't get Mojang names for free. Their authors had to recompile them against Mojang mappings, and some slow-moving projects never did.
From 26.1, the game jar ships with Mojang's real names, so there's nothing left to deobfuscate. Paper no longer remaps plugins at all. An NMS plugin built with Spigot's reobfuscated mappings won't load on Paper 26.1 or newer until its author publishes a build that targets Mojang names. Authors who use paperweight-userdev already build against Mojang names, and that happens when the plugin is compiled, not when your server starts.
If you've ever seen a plugin's release notes mention "now built for Mojang mappings" or "supports Paper 1.20.5+", that switch is what they mean.
How plugin authors keep up
Authors who care about surviving version bumps do a few things.
They stick to the API when they can. A plugin that never touches NMS almost never breaks on a version update. It might need a rebuild to target a newer Java version, or a small tweak because Paper deprecated an old method, but it doesn't shatter. Economy plugins, permissions plugins, simple chat plugins, land claim plugins that use the Bukkit block API: these tend to work across versions with little fuss.
They ship a separate module per version. A plugin that has to use NMS often splits its code: one core module with the shared logic, and per-version modules named things like v1_20_R4 or v1_21_R1. At startup the plugin detects the server version and loads the matching module. This is the pattern behind long-running heavyweights like ProtocolLib, Citizens and WorldEdit. It's more work for the author, but the plugin can support many Minecraft versions from a single jar.
They use a compatibility layer. ProtocolLib in particular is a common dependency because it hides most of the NMS churn behind its own API. A plugin that would otherwise have to rewrite its packet handling for every Minecraft version can rely on ProtocolLib to do that work once. The cost is that when a new Minecraft version drops, everything downstream of ProtocolLib has to wait for ProtocolLib itself to update first.
They use reflection carefully. Some authors avoid direct NMS imports and reach the same code through Java reflection, looking up classes and methods by name at runtime. That doesn't make the plugin version-proof, but it does mean it fails softer and can sometimes be patched without a full rebuild.
Reading the signs before you update
When a new Minecraft version comes out, the question every admin ends up asking is which plugins are safe to bring along and which ones are going to hold the whole update back. A few signals help.
Look at what the plugin does. A plugin whose whole job is to spawn custom mobs, rewrite chunk generation, intercept packets or replace vanilla features almost certainly uses NMS. It'll need an update before you move. A plugin that stores balances, manages regions or hands out ranks probably doesn't.
Check the supported versions on the plugin page. Modrinth, Hangar and SpigotMC all list which Minecraft versions the current build targets. A plugin that already lists the new version, even for a snapshot build, is a good sign. A plugin whose newest release is years old and stops at 1.19 is not.
Check NMS plugins for 26.x. An NMS plugin whose newest build only lists 1.21.x versions hasn't said anything about 26.x yet. With the mappings change above, don't assume it'll load on 26.1 until the author ships a build that lists it.
Watch for the stable release, not just the experimental build. Big plugins often ship an experimental build within days of a new Minecraft version, followed by a stable release once the community has found the sharp edges. If you can wait for the stable one, do.
Look at dependency chains. If a plugin depends on ProtocolLib, PacketEvents or a similar core library, that library has to update first. Check its release page before you start blaming the plugin on top.
Trust the plugins with a track record. Names that have been through many Minecraft versions already, such as EssentialsX, LuckPerms, CoreProtect, WorldGuard, WorldEdit, Vault and ViaVersion, tend to get updated quickly because they have active teams behind them. A single-author plugin with a handful of downloads is a bigger gamble.
What this looks like in practice
Most servers have a mix. There's a stack of small, API-only plugins that survive every update untouched, a handful of medium plugins that need a rebuild, and one or two heavyweights that gate the whole migration. The realistic upgrade timeline for a plugin-heavy server is often a few weeks after a Minecraft release, not the day of. That's normal. Waiting is cheaper than restoring a broken server from backup.
It also helps to keep a test server on the new version, even a tiny one, so you can bring plugins over a few at a time and see what falls over before you touch production.
A note on server software choice
Paper is the mainstream Bukkit-family server for a reason: the API is stable, the release cadence is quick, and most plugins target it directly. Forks like Purpur add extra features on top but inherit Paper's plugin surface. Folia changes the threading model and breaks any plugin that assumed a single main thread, which is a much bigger compatibility break than a normal version bump. If you run Folia, expect a smaller plugin pool.
Spigot still works but trails Paper on features and performance work. Vanilla and Fabric don't run Bukkit plugins at all, so the whole conversation above doesn't apply to them. Modded servers have their own version pain, tied to Forge, NeoForge or Fabric loader updates, which is a different post.
If you'd rather someone else worry about the version churn between updates, ChunkPod is a Minecraft server host in early access. You can join the waitlist at chunkpod.com to get notified when hosting opens.