Mojang announces a new Minecraft version. Your players want it immediately. You update the server JAR, start it up, and half your plugins throw errors. The economy is broken, permissions are gone, and the world border shows corrupted chunks where the new terrain generation meets the old one.
This happens every major update. Here is how to avoid it.
Why Updates Break Things
Major Minecraft versions change internal code that plugins depend on. When Mojang renames a method, changes packet format, or modifies the NBT structure, plugins that use those internals crash on startup.
Common breakage points:
- NMS (Net Minecraft Server) code: Plugins that access Minecraft internals directly break almost every major version
- API changes: Bukkit and Spigot APIs sometimes deprecate or remove methods
- Data format changes: NBT tags, item component format (changed in 1.20.5), chunk format
- World generation: New biomes and structures change how terrain generates
Step 1: Do Not Update on Day One
When a new Minecraft version drops, resist the pressure to update immediately.
Wait for:
- Paper to release a stable build for the new version (usually 1-3 days)
- Your essential plugins to confirm compatibility (check each plugin's SpigotMC page or Discord)
- ViaVersion to support the new version (so players on the new client can still join your current version server)
Install ViaVersion on your current server. This lets players who updated their client connect to your older server version. You buy time without losing players.
Step 2: Audit Your Plugin List
Go through every plugin on your server. For each one, check:
- Last update date: If the plugin has not been updated in over a year, it may not support the new version
- Developer activity: Check their GitHub or SpigotMC page for recent activity
- Known alternatives: If a plugin looks abandoned, find a replacement before you are forced to
Make a spreadsheet or list:
| Plugin | Current Version | Dev Active? | Alternative | |---|---|---|---| | EssentialsX | 2.21.0 | Yes | N/A | | CustomPlugin | 1.2.3 | Last update 2024 | Consider replacing | | ShopGUI+ | 1.89.0 | Yes | N/A |
Plugins that are likely to break on a major update:
- Anything that uses NMS (packet manipulation, custom entities)
- Protocol hacks (ViaVersion itself needs updating first)
- Plugins that modify world generation
- Anything that uses custom NBT data formats
Step 3: Set Up a Test Server
Create a test server running the new version. See our test server guide for how to set this up.
- Install the new Paper version
- Copy all your plugin JARs
- Start the server and check console for errors
- Test each plugin one by one
Do not add all plugins at once. Start with just Paper and no plugins. Then add them one at a time, restarting between each. When something breaks, you know which plugin caused it.
Step 4: Handle World Generation Changes
New Minecraft versions often add biomes, blocks, and structures. These only generate in new chunks (chunks that have never been loaded before). Your existing world keeps its current terrain.
This creates ugly borders where old terrain meets new terrain at chunk boundaries. You have three options:
Option A: Live with it. Players must travel past explored areas to find new content. Chunk borders are visible but functional.
Option B: Reset the nether/end. Most servers reset the Nether and End dimensions on major updates. These dimensions are smaller and resetting them gives players access to new content without touching the overworld.
To reset the Nether:
- Stop the server
- Delete the
world_netherfolder (or rename it as a backup) - Start the server. A fresh Nether generates with the new content
Option C: Full world reset. Start a completely new world. This only makes sense if your server is young or if the update changes overworld generation significantly.
Step 5: Back Up Everything
Before touching anything on your production server:
- Stop the server
- Download the entire server directory (all files, all folders)
- Store this backup somewhere safe (local PC, cloud storage, external drive)
If the update goes wrong, you can restore this backup and be back to normal in minutes.
Step 6: Update Day Checklist
When you are ready to update:
| Step | Action | |---|---| | 1 | Stop the production server | | 2 | Take a full backup | | 3 | Update Paper JAR to the new version | | 4 | Update all plugins to their latest versions | | 5 | Delete or rename old world_nether and world_the_end if resetting | | 6 | Start the server | | 7 | Watch console for errors for 5 minutes | | 8 | Join and test core functionality (homes, warps, economy, permissions) | | 9 | Open the server to players | | 10 | Monitor for 24 hours |
What If a Plugin Does Not Support the New Version?
You have three choices:
- Wait. Stay on the current version until the plugin updates. Use ViaVersion to let updated clients connect.
- Replace it. Find an alternative plugin that supports the new version.
- Remove it. If the plugin is not essential, remove it and see if players even notice.
Do not use plugins on a version they do not support. They might load without errors but corrupt data silently.
Timeline Expectations
Based on past releases:
| Software/Plugin | Typical Wait | |---|---| | Paper | 1-3 days | | Spigot | Same day to 1 day | | EssentialsX | 1-7 days | | LuckPerms | Usually same day | | WorldGuard | 1-7 days | | ViaVersion | Same day | | Small/niche plugins | 1 week to never |
Plan for a 1-2 week update window where you stay on the old version, test everything on a staging server, and only push the update when all your essential plugins are confirmed working.
Space-Node supports all Minecraft versions through the Pterodactyl panel. Switch versions with a one-click JAR selector. Check the plans here.
