Updating Paper: Move to a New Minecraft Version Without Breaking Plugins

This guide is for server owners who run Paper and want to move to a new Minecraft version without waking up to broken plugins or a damaged world. By the end you will have a repeatable routine: back up, test on a copy, check every plugin, update the live server, and a clear way back if something fails.

Know why an update cannot be undone#

Paper's release notes repeat the same warning every time: after you upgrade a world to a new version, you cannot downgrade it to a lower one, and backups are mandatory. This is stated in the announcements for Paper 26.3 (released 26 September 2026), 26.2 and 26.1. A Paper developer explained on the forums that the conversion of chunks, entities and player data is only written in one direction.

That one fact shapes the whole routine. Your "rollback" is never a downgrade. It is a restore of a backup you took before the update, so the backup is the most important step. The official Paper update guideSource site calls it the step that is most often skipped.

Paper Free The Minecraft server software most plugin-based servers run on, with stable and experimental build channels. On PaperMC

Choose the right build channel first#

Paper builds come in three channels: stable, beta and alpha. The Paper downloads service docsSource site say to use stable builds and describe experimental builds as prone to error and unsupported. They also say they do not recommend unstable builds or auto-updaters in production.

When we checked on 3 October 2026, the Paper downloads page showed 26.2 build 129 as the stable download, with experimental 26.3 builds switched off by default. Paper's download API listed the newest 26.3 builds (139 to 143) in the beta channel. Check the page again on the day you update, because this changes quickly.

Back up everything before you touch anything#

Paper's guide says to back up the world folders, the server configuration files and the plugin JARs, and to keep rolling backups so you always have several from different times. Also back up your plugin data folders, because that is where configs and sometimes databases live.

stop
cd /home/minecraft/server
mkdir -p ~/backups
tar -czf ~/backups/server-before-update.tar.gz .

Make a test copy of the server#

A test copy lets the new Paper version upgrade a copy of your world while the real one stays safe. The best way to build it is from your backup, which also tests the backup.

mkdir -p ~/test-server
tar -xzf ~/backups/server-before-update.tar.gz -C ~/test-server
cd ~/test-server
nano server.properties

Before you start the copy, cut its links to anything live. This is the part people forget:

• Point plugins that use MySQL or another database at a test database, not the live one.
• Remove or replace Discord bot tokens, webstore keys and vote-site keys.
• Take the copy off any proxy network, or give it its own secret.
• Turn on the whitelist so random players cannot join it.

Check every plugin before you update#

Most breakage after an update comes from plugins, not from Paper. Work through your plugin list one by one.

1. List your plugins with /plugins in the console, and note the version of each.
2. Open each plugin's official page (Modrinth, Hangar, SpigotMC or BuiltByBit) and read the supported versions and the changelog. Do not assume an old plugin will work on a new server version.
3. Mark each plugin as updated, no update needed, or abandoned. Abandoned plugins on a new version are the usual cause of trouble, so look for a maintained alternative while you still have time.
4. Check libraries and dependencies too. Paper's troubleshooting guide specifically points to keeping libraries such as ProtocolLib current.

Paper gives you one useful clue. A plugin declares the Paper API version it was built for in api-version inside its plugin.yml. According to the Paper plugin.yml docsSource site, a server older than the declared version refuses to load the plugin, and a plugin with no api-version is loaded as a legacy plugin with a warning in the console. Treat that legacy warning as a sign the plugin is old.

Update plugins with the update folder#

Paper has a built-in way to swap plugin JARs safely. Create a folder called update inside plugins, put the new JARs in it, and restart. The server swaps them in at startup, so you never replace a JAR while the server is running. Paper's guide warns against replacing JARs in a running server.

Run the update on the test copy#

Download the new Paper JAR from the official downloads page. Paper's guide says to stop the server, rename the new file to match your start command, replace the old JAR and start again while watching the log.

First check Java. The Paper getting started docs say Paper 26.1 and newer needs at least Java 25. Check which Java your host or machine really uses before you start.

java -version
cd ~/test-server
mv paper.jar paper-old.jar
# put the new download here and name it to match your start command
mv paper-26.3-BUILD.jar paper.jar
java -Xms4G -Xmx4G -jar paper.jar --nogui

Pterodactyl Free The open source game server control panel that most Minecraft hosts use, with a File Manager, Backups tab and Startup settings. On Pterodactyl

Read the log from the top on the first boot. Look for plugins that failed to enable, red stack traces, missing dependency messages and legacy plugin warnings. Then test what your players really do:

1. Join with a normal account and a staff account.
2. Check spawn, warps, menus and NPCs.
3. Test the economy, shops, ranks and permissions.
4. Play each minigame or arena mode through once.
5. Run any scheduled tasks, such as world resets or crates and rewards.
6. Test your backup and restart scripts.

If your last update was before 26.1#

Paper's 26.1 announcement describes a change in how worlds are stored: dimensions are split into separate folders under world/dimensions/, and per-world Paper config files moved into the dimension folders. Anything that hard-codes the old folder layout, such as backup scripts, world reset tools or file-copy tasks, needs checking. The same post introduces a time.affects-all-worlds setting for per-world time, so read it if you run several worlds.

Update the live server with a way back#

When the test copy runs cleanly, repeat the same steps on the live server. Do it when your server is quiet, tell players in advance, and stay online for a while afterwards. Paper's guide says to be present during updates and to watch the log afterwards, and it does not recommend automatic updates.

1. Announce the maintenance window.
2. Stop the server and take a fresh backup, even if you made one earlier.
3. Put the new plugin JARs in plugins/update and swap the Paper JAR.
4. Start the server and watch the log.
5. Join and run your short test list again.

Write the rollback plan before you need it#

Because downgrades are not supported, rolling back means restoring. The PaperMC forum answer to "can't roll back server version" gives two options: stay on the new version and find compatible plugins, or restore from a backup made before the upgrade. Keep these ready:

• The pre-update backup, stored off the server.
• The old Paper JAR and the old plugin JARs.
• A note of the exact restore steps for your host (extract the archive, or press Restore on the Backups tab).
• A cut-off time: if it is still broken after that time, restore and try another day.

Check performance after the update#

A server that starts is not always a server that runs well. Give it an hour of real play, then profile it. spark is a free profiler that shows TPS, tick times and what is eating CPU, and our guide on pregenerating your world and finding lag with spark shows how to use it.

spark Free A free performance profiler that reports TPS, tick duration and CPU or memory use so you can compare before and after an update. On Modrinth

Keep your backup for at least a few days after the update, and keep your rolling backups going. When a plugin author releases a fix, update through the update folder again, one plugin at a time, so you know which change caused any new problem.