Upgrading a Minecraft server from 1.21.11 to 26.1

What actually changes

This is not an ordinary point upgrade. Three things move at once, and each one can stop the server on its own:

1. The Java requirement goes up. 1.21.11 runs on Java 21. The calendar releases want a newer runtime. Check the exact figure for both versions with the Java version checker rather than trusting a number in a forum post, because it comes from Mojang's own metadata for that version.
2. The world format moves forward. Loading a 1.21.11 world on 26.1 converts it, and the conversion cannot be undone.
3. The server API changes. Plugins compiled against the 1.21 API will not all load. This is where most upgrades actually fail.

Do them in that order. Java first, because it is the only one you can test without touching your world.

Step 1: back up, and restore the backup

A backup you have never restored is a file, not a backup.

# Stop the server first. A copy of a running world is a copy of a half-written world.
systemctl stop minecraft

tar -czf ~/backups/pre-26.1-$(date +%F).tar.gz \
  world world_nether world_the_end plugins server.properties

# Now prove it works: unpack into a scratch directory and start a server on the OLD
# version pointing at it. If that world loads, you have a way back.

Everything after this point is reversible only because of this step. If the restore test fails, stop and fix that before going any further.

Step 2: move to the new Java before you touch the server jar

Upgrading Java and the server at the same time means that when something breaks you will not know which change broke it. So do Java on its own, on the version you are already running.

java -version          # what you have now

Install the runtime 26.1 requires, point your start script at it explicitly rather than relying on whatever java resolves to, and start your 1.21.11 server on it. Older Minecraft versions run fine on newer runtimes in almost every case, so this should be a non-event. If it is not a non-event, you have found a problem worth finding now rather than in the middle of the real upgrade.

Verified builds for every Java version we track are listed under Java, with checksums, straight from Adoptium.

Step 3: confirm a stable build exists for 26.1

Not every server project ships a stable build for a new Minecraft version on release day, and a build marked experimental is a build the project is telling you not to run in production yet.

Check what runs on 26.1. If your server software has a stable build there, note the build number. If it only has an experimental one, this is the moment to wait rather than the moment to push through.

Step 4: inventory your plugins

This is the step that decides whether the upgrade takes an hour or a weekend.

List every jar in plugins/. For each one, find its project page and check whether it declares support for 26.1. Sort the list into three piles:

• Supported. Download the 26.1 build. Do not keep the old jar.
• Not supported yet, and maintained. Check the project's own issue tracker for an estimate. If several of these land in this pile, the answer is to wait.
• Not supported and abandoned. Find a replacement now, or accept that the feature goes away. An unmaintained plugin does not get more maintained by being upgraded around.

The plugin catalogue filters by Minecraft version directly, and the support claim on each project comes from the author's own release metadata rather than from a table somebody keeps by hand.

Step 5: convert a copy first

Never convert the live world as the first thing you do.

cp -r world world-testconvert

Start a server on 26.1 pointing at world-testconvert, with no plugins at all. Let it load, fly around the spawn area, check the log for conversion errors, then stop it.

A clean conversion with no plugins tells you the world is fine. If you skip this and go straight to converting with thirty plugins loaded, an error in the log tells you nothing about which of the thirty-one moving parts caused it.

Then add plugins back in groups, not all at once. Permissions and economy first, since everything else usually depends on them.

Step 6: cut over, and what to watch in the first hour

Announce the downtime, stop the server, swap the jar, start it, and then watch these four things:

• The startup log, in full, once. Every plugin that failed to load says so there, and it says so once, at startup, and never again.
• Tick time. A new Minecraft version plus freshly converted chunks is the worst case for server performance. If tick time is bad in the first hour, give it a few hours of play before concluding anything, because chunk conversion is a one-time cost.
• Permissions. The most common post-upgrade complaint is that somebody lost access to something, and it is almost always a permissions plugin that loaded but did not read its old config.
• Whether players can actually connect. A client on 1.21.11 cannot join a 26.1 server. Say so in the announcement, because half your player base will not have read it.

Keep the backup until the server has run a full week without anyone reporting anything. Then keep it anyway.