Why an update is one-way
When a newer server opens your world, it rewrites the files into the newer format as it saves. After that the old version cannot safely open them again: the Minecraft Wiki warns that a world opened in a version older than the one that saved it may become corrupted, and PaperMC's 26.1 announcement says plainly that after upgrading a world to 26.1 you cannot downgrade to a lower version.
The point of no return is the first start on the new jar, not the moment you upload it. Until then you can still change your mind. After it, the backup is the way back.
Your players also have to move with you. A Java client can only join a server on the same version, and the rest get Incompatible client with the version they need. Tell everyone before you update, and see the can't-connect fixes if anyone is turned away afterwards.
- The first start on the new version converts the world
- No downgrade afterwards: restore the backup instead
- Every player needs the same version as the server
Check plugins, mods and Java before anything else
Plugins need checking first, because each one is built against particular versions. Open each plugin's page on Hangar, Modrinth or wherever you got it, and confirm there is a release for the version you are moving to. If a plugin your server depends on has no release yet, wait. Running it on a version it was not built for is how a server starts with half its features red.
Moving to 26.1 or later is a bigger step than most. Mojang no longer ships an obfuscated server, and Paper dropped its internal remapper in 26.1. Paper's announcement says this matters for plugins that use server internals, directly or through reflection, and those need a release built for 26.1.
Check Java at the same time. Minecraft 1.20.5 to 1.21.11 need Java 21, and 26.1 and everything after need Java 25. A server started on an older Java than the game needs will not start at all. Modded servers wait for their loader too: the Fabric, Forge or NeoForge build and every mod need a release for the new version before you move.
- Every plugin or mod has a release for the target version
- 1.20.5 to 1.21.11: Java 21
- 26.1 and later: Java 25
- Modded: the loader and all mods are ready
Back up the whole server, and keep a copy off it
PaperMC's update guide starts here, and lists what to include: the world folders, the server's configuration files, and the plugins with their configuration folders. In practice that means the whole server directory. Paper also recommends keeping several backups from different times.
On Puranode every server gets a nightly backup, and you can start one with a click in the panel before the update. Game plans hold one backup slot, which always holds the latest backup. Download the file once it finishes, so you hold a copy of the pre-update server that no later backup can overwrite. Full SFTP access lets you copy the server folder yourself as well.
If you want a dry run, restore the backup onto a test setup and try the update there first. That is the only way to see what your exact plugin list does on the new version before your players do.
- World folders, including world_nether and world_the_end on Paper before 26.1
- server.properties, bukkit.yml, spigot.yml and Paper's config folder
- The plugins folder: jars and their config folders
- A downloaded copy you keep off the server
Update a Paper server, step by step
Never replace a jar while the server is running, whether it is Paper or a plugin. Paper's guide lets you update the plugins and the server in a single restart: plugin updates go in a folder named update inside plugins, and the server swaps them in as it starts.
The new Paper jar has to be the file the server actually starts. Paper's guide says to rename it to the name in your start command and replace the old jar, or upload it under a new name and point the start-up at it. On Puranode that is the Server Jar File setting in the panel.
Start the server and watch the console the whole way through. The world conversion happens here, so let it finish. When it is up, run version to confirm the new build and plugins to check every name is green.
- Download the new build from Paper's downloads page
- Put updated plugin jars in plugins/update
- Stop the server
- Replace the old Paper jar with the new one, same file name, or change the Server Jar File setting
- Start the server and read the log for plugin errors
- Run version and plugins, then join and look around
What 26.1 changes on disk
If your server is moving from 1.21.x to 26.1 or later, the world folder will look different afterwards, and that is expected. From 26.1 all default dimensions are stored in a dimensions subfolder: the overworld in dimensions/minecraft/overworld, the Nether in dimensions/minecraft/the_nether and the End in dimensions/minecraft/the_end.
Paper follows the same layout. Before 26.1, Paper kept the Nether and End as separate world_nether and world_the_end folders beside world. From 26.1 they move into world/dimensions, and Paper's per-world configuration files move with them. Any script, backup rule or tool that pointed at the old folder names needs updating too.
If you later upload a world from singleplayer, match it to the server's version the same way: same or newer is fine, older is not.
- Overworld: dimensions/minecraft/overworld
- Nether: dimensions/minecraft/the_nether
- End: dimensions/minecraft/the_end
- Paper: world_nether and world_the_end merge into world/dimensions
Vanilla servers, and the optional full upgrade
A vanilla server updates the same way: back up, stop, replace server.jar with the new one from Minecraft's official server download page, and start. Java requirements are identical.
Paper documents a start-up flag, --forceUpgrade, that forces a full world upgrade on server start instead, and --eraseCache, which erases cached data during that upgrade. Start-up arguments go directly after the server jar's file name. Use them for one start if you want the whole map converted at once, then take them out again.
After the update, give the server a little time before judging performance. If ticks are slow, the lag and low TPS guide shows how to find what is responsible, and the server.properties generator helps if you want to compare your settings with a clean file.
If something goes wrong after the update
Do not point the old jar at the converted world. That is exactly the downgrade both Mojang and Paper warn against. Decide instead whether the problem is a plugin or the world.
If a plugin is red, read logs/latest.log for its error, then update it, remove it, or wait for a release for your version, keeping the server on the new version. If the world itself is wrong, or a plugin you cannot do without has no release yet, stop the server, restore the whole backup, put the old jar back and start again. Then try the update later.
Paper does not recommend automatic updates, because plugin conflicts can appear without warning, and nothing on our side updates your server jar for you. Your version stays exactly where you put it until you choose to move.
- Red plugin: fix or remove it and stay on the new version
- Broken world or missing essential plugin: restore the full backup and the old jar together
- Never open the converted world with the old jar