Upgrading a Minecraft server version without losing the world

A world opened by a newer version is converted, and the conversion is one-way. That single fact decides the whole procedure: the backup you take before an upgrade is not a precaution, it is the only way back. Everything else - the order of the steps, the staging copy, the plugins you check first - exists to make sure you never need it.

The short version, for people who have done this before: check the Java version the target release needs, check every plugin has a build for it, take and download a backup, upgrade a copy first, start the new jar with the plugins folder renamed and nobody online, read the console, then put the plugins back a few at a time. The long version explains why each of those steps is there and what it catches.

Three things change at once#

"Upgrading the server" is really three separate upgrades that happen to be triggered by the same click, and they fail in different ways.

The world format. Every chunk and every entity is stored with a data version. When a newer server loads an older chunk it runs it through a chain of converters - the DataFixer - and writes it back in the new format. This happens lazily: a chunk is converted when a player walks into it, so a world can sit half-converted for weeks. level.dat records the version the world was last opened with, and that is the value an older jar will refuse or mishandle.

The server software. Vanilla, Paper, Fabric and the rest each cut their own build for a release, and the first builds after a Minecraft release are experimental for a reason. Paper in particular marks early builds for a new version as not recommended for production, and that label is honest - the crashes in week one are real.

The plugin or mod API. This is where almost all the pain is. A plugin written against the Bukkit API and nothing else usually survives a minor bump untouched. A plugin that reaches into server internals - and that is most anti-cheats, most protocol plugins, and anything that adds custom items or entities - breaks on every single version, without exception, until its author ships a new build.

To that add a fourth thing that is not a Minecraft change at all but breaks startup just as hard: the Java version.

Which Java version each release needs#

The failure is loud and unmistakable: UnsupportedClassVersionError ... has been compiled by a more recent version of the Java Runtime. If you see that line on startup, nothing about your world or your plugins is wrong; the container is running an older Java than the jar needs. On a panel this is a variable on the Startup tab rather than a package to install. On RE:NODE the Minecraft egg runs Paper with the matching Java version already, so the common case is handled, but check it before a jump across one of the lines in that table.

Running a newer Java than required is generally fine and often better. Running a newer Java than your plugins expect occasionally is not, so if one plugin fails to load after a Java bump while the server is otherwise healthy, that is the first thing to test. Heap sizing and garbage collection flags change with the Java version too - JVM flags and Java versions goes through which flags still make sense on 17 and 21.

The upgrade, in order#

1. Read the release notes for the server software, not just the game. Paper's notes list the config migrations and the removed APIs, which is where most surprises live.
2. List your plugins and check each one. version in the console prints the server build; plugins lists what is loaded. Open each plugin's page and confirm there is a build for your target version. Write the list down - this is the step that decides whether the upgrade happens at all.
3. Announce a window. Ten minutes is usually enough; say an hour so you are not rushed.
4. Stop cleanly. save-all flush, wait for it to finish, then stop. Never upgrade a world that was killed rather than stopped.
5. Take a backup and download it. Not "create a backup" - download the file and confirm the archive opens. A backup nobody has restored is a hypothesis. Testing a restore before you need it is twenty minutes that pays for itself once.
6. Upgrade a copy first if you possibly can. A second small server with the world and plugins copied onto it tells you in twenty minutes what production would have told you in front of an audience. Staging and production on one account covers doing this without paying much.
7. Change the version and start with no plugins. Rename plugins to plugins.off and start. You are testing exactly one thing: that the world converts and the server reaches "Done".
8. Read the console while it converts. A big world takes minutes, and chunk conversion is CPU-bound. Reading the console is the skill this step needs.
9. Put plugins back in batches. Core first - permissions, protection, economy - then the rest in groups of three or four, restarting between. When something breaks you know which batch did it.
10. Check the quiet things. Permissions still apply, homes still work, the block log still queries, custom recipes still craft, shops still take money.
11. Announce it afterwards, once you know it worked. Not before.

Nobody has ever regretted taking one more backup before an upgrade.

Converting the whole world at once#

Because conversion is lazy, the first few weeks after an upgrade spread the cost across every session, and a player exploring old terrain pays it in stutter. You can do it all up front instead. Stop the server and start it once with the vanilla upgrade flag:

$ java -Xms4G -Xmx4G -jar server.jar --forceUpgrade --nogui

The server walks every region file, converts every chunk, prints a percentage, and exits. Add --eraseCache to throw away the cached lighting and heightmaps as well, which fixes the lighting artefacts that sometimes survive a big jump at the cost of a longer run.

Two warnings. This is the moment a world without a border becomes expensive: a 40 GB world of chunks nobody has visited since 2023 takes hours to convert and you gain nothing from it. Setting a border and trimming first is the cheaper order - see world borders and pre-generation. And on Paper a long conversion can trip the watchdog, which is looking for a tick that never finished; if the panel shows a restart loop during conversion, run it once with the flag and let it exit rather than leaving the normal start command in place.

What breaks, and how to tell before you find out#

Check these against the target version specifically, not against "recently updated":

• Anything protocol-level. Protocol libraries have to be rebuilt for each version and are frequently the last piece of the puzzle to arrive. Plugins depending on them stay broken until they do.
• Anti-cheat. It reads movement and internals by design, so it is version-locked by design.
• Custom item and custom entity plugins. These write data into items and blocks; a mismatch does not just fail to load, it can corrupt what it wrote.
• World editing and map plugins. Usually fine, but they touch chunk internals, so test with a throwaway region rather than your spawn.
• Anything abandoned. Check the date on the latest release before you check the version list.

In the jar, plugin.yml carries an api-version line. A plugin that declares nothing is treated as pre-1.13 legacy, and modern Paper builds complain loudly about those and may refuse to load them outright. If a plugin still has no api-version in 2026, treat that as the answer about whether it is maintained.

Paper's move to Mojang mappings in 1.20.5 added an automatic remapper for older plugins, which quietly fixed a whole class of "this plugin was built for the wrong mappings" failures. It is not magic - a plugin calling a method that no longer exists still fails - but it means "built for 1.20.4" is less often fatal than it used to be.

Sooner or later one plugin will hold the whole server on an old version. That is a real choice, not a failure: either the feature matters enough to stay where you are, or it does not and you remove it. What does not work is upgrading anyway and hoping. Plugins worth installing leans towards the well-maintained ones for exactly this reason, and what to do when a mod update breaks is the modded equivalent of this whole post.

Datapacks, resource packs and the quiet breakages#

Datapacks declare which version they were written for, and the number changes nearly every release:

{  "pack": {    "pack_format": 41,    "description": "Vanilla tweaks"  }}

The 41 above is an example, not a value to copy - each release has its own number, and a pack carrying the wrong one is listed as incompatible. Check with datapack list after the upgrade; anything in the disabled list needs a new download or a corrected pack.mcmeta. Custom functions can also break on syntax changes, which produce errors at load rather than silence. The datapacks guide covers ordering and debugging them.

Resource packs are simpler but catch people the same way. resource-pack, resource-pack-sha1 and require-resource-pack in server.properties point at a file; if you re-export the pack for a new version and do not update the hash, clients refuse it and you get a wave of confused messages. Update the file and the hash together.

server.properties itself gains keys between versions - simulation-distance arrived in 1.18, enforce-secure-profile in 1.19 - and the server writes any missing key with its default on first start. Keep a copy of the old file and compare it with the new one afterwards. Anything that appeared is a new default you did not choose. Every key is explained in server.properties explained.

Letting older clients in#

Three plugins solve the "half my players have not updated" problem, and it is worth knowing which is which:

They are translation layers, not time machines. A 1.8 client on a modern server cannot see blocks that did not exist in 1.8, and anything that relies on new packet types will behave oddly for them. They are excellent for a two-week transition and a poor permanent architecture. If your community is genuinely split across versions for good, a proxy in front of per-version backends is the honest answer - what a reverse proxy does explains the shape of that.

Rolling back#

There is one reliable rollback and it is the backup. Restore the world folder and the plugins folder together from the copy you took at step 5, put the old jar back, and start. You lose whatever was played since the backup, which is why the window matters and why you take the backup immediately before the upgrade rather than "last night's".

What does not work is pointing the old jar at the converted world. Depending on the version it will refuse to start, or it will start and quietly drop the parts of each chunk it does not understand, which is worse. Treat the converted world as a one-way door and the backup as the door back.

The other half of a good rollback is knowing quickly that you need one. Keep the old world archive until the new version has survived a busy evening, not until the upgrade finished. Backups that actually restore is the longer argument; the short one is that the copy that matters is the one you have downloaded, off the machine it protects.

Troubleshooting the messages you will actually see#

`UnsupportedClassVersionError` - the Java version is older than the jar needs. See the table above.

`NoSuchMethodError` or `NoClassDefFoundError` in a plugin's stack trace - that plugin was built for a different server version. Not fixable by you; replace it or wait.

"Could not load 'plugins/Something.jar'" followed by an InvalidPluginException - usually a missing dependency, because you put the plugins back in the wrong order. Restart with the dependency present.

"Outdated server!" or "Outdated client!" in the multiplayer list - a protocol mismatch, and the version named in the message is the one you need to match. "Outdated server" means the server is behind the player's client.

"Failed to check session lock for world" - another process has the world open, or a previous process died without releasing it. Make sure only one server points at that folder, then restart.

Chunk borders with a visible cliff - expected after a terrain-generation change such as the 1.18 height increase. New chunks are generated by new rules next to old ones. Blending softens it but does not erase it; the only cure is pre-generating the area you care about before the change, or accepting it as scenery.

Mobs stop spawning in old chunks - biome or spawn-rule changes usually, occasionally a simulation-distance that came in as a new default lower than your old effective range.

FAQ#

Can I go back to an older Minecraft version after upgrading?

Not with the same world. The conversion is one-way, and an older server given a converted world either refuses it or silently loses data. Going back means restoring the backup you took before the upgrade and accepting the loss of everything played since.

Do I have to upgrade at all?

No. A server can stay on an older release indefinitely, and plenty do because one plugin or one modpack anchors them. The costs are that players on new clients need ViaVersion to join, security fixes stop arriving, and the further behind you fall the larger the eventual jump.

How long does the world conversion take?

Lazily, you never notice it as one event. All at once with --forceUpgrade, budget minutes for a small bordered world and hours for tens of gigabytes. The size of your world folder is the number that predicts it, which is a good argument for having a border in the first place.

Should I upgrade on release day?

No. Wait for your server software to publish a build it is willing to call stable for that version, and wait for the plugins you cannot live without. Two weeks is usually enough and costs you nothing.

Do I need to upgrade plugins and the server at the same time?

Update the server first with the plugins folder set aside, confirm the world converts, then add plugins back in batches. Doing both in one step means any failure has two possible causes and you will spend the evening telling them apart.

Will my players' inventories and builds survive?

Yes - player data and the world are both converted forward, and this part is reliable in practice. What does not survive is data written by a plugin that you then removed because it had no build for the new version; that data stays in the world files, unread and invisible.