How to Update Your Minecraft Server to 1.21 Safely

Before You Touch Anything: Back Up Everything

This is not optional advice you can skip because you have done updates before. Updating a Minecraft server to a new major version like 1.21 involves changes to world data formats, plugin APIs and Java requirements. If something goes wrong, you need a clean copy of your current state to roll back to. Here is what to back up:

• Your entire server directory, every folder, every config file, every world.
• Your database if you use MySQL/MariaDB for plugins like LuckPerms, LiteBans, or economy plugins. Run mysqldump -u root -p minecraft_db > backup_pre121.sql.
• Your startup script and Java path, because those may need to change.

Store the backup somewhere outside the server directory. If your server runs on a host with a panel, use the panel's backup feature and also download a copy locally. Hosting panels occasionally lose data too.

Check Java Version: 1.21 Requires Java 21

Minecraft 1.21 and Paper 1.21 require Java 21 at minimum. If you are coming from 1.20 or older, you are probably running Java 17. Check your current version:

java -version

If it says anything below 21, you need to install Java 21. On Debian/Ubuntu:

sudo apt install openjdk-21-jre-headless

If you use a hosting panel like Pterodactyl, switch the Docker image to one that includes Java 21. Most hosts label these clearly, look for "Java 21" or "Minecraft 1.21+" in the egg or startup settings. See our Java 21 vs Java 17 comparison for more details on version requirements and performance differences.

Check Plugin Compatibility

This is the step that takes the most time and saves the most headaches. Go through every plugin in your plugins/ folder and check if it supports 1.21.

• Visit the plugin's page on SpigotMC, Modrinth, or Hangar. Look at the "Tested Minecraft Versions" tag or the latest changelog.
• Check the plugin's Discord server or GitHub issues for 1.21 compatibility reports.
• If a plugin has not been updated in over 6 months and the developer has not posted about 1.21, assume it is broken until proven otherwise.

Make a spreadsheet or list with three columns: plugin name, current version, and 1.21 status (ready / update available / unknown / abandoned). Prioritize plugins that affect core gameplay, economy, permissions, world protection. Cosmetic plugins can wait.

Plugins That Commonly Break on Major Updates

Plugin Type	Why It Breaks	Action
Custom enchants	Enchantment registry changes in 1.21	Wait for update or disable temporarily
World generators	Internal chunk format changes	Test on a copy world first
NMS/packet plugins	Direct server code access changes every version	Must update to 1.21-specific build
Anti-cheat	Movement and combat calculations shift	Update and reconfigure, false positives are common after version bumps

Download the New Server Jar

Get the latest Paper, Spigot or Purpur build for 1.21 from their official sites. Do not download jars from random forum posts or mirror sites, they may contain malware.

• Paper: https://papermc.io/downloads/paper, select 1.21, download the latest build.
• Purpur: https://purpurmc.org/downloads, same process.
• Spigot: You need to run BuildTools with --rev 1.21 to compile the jar.

Rename the jar to something consistent like server.jar and replace the old jar in your server directory.

Update Your Startup Script

If you hardcoded a Java path in your startup script, update it to point at Java 21:

# Old
/usr/lib/jvm/java-17-openjdk-amd64/bin/java -Xms4G -Xmx4G -jar server.jar

# New
/usr/lib/jvm/java-21-openjdk-amd64/bin/java -Xms4G -Xmx4G -jar server.jar

Also review your JVM flags. The Aikar flags that worked on Java 17 generally work on Java 21, but check the optimization guide for any recommended changes. ZGC got significant improvements in Java 21 and may be worth trying if you were previously using G1GC.

Test on a Copy First

Never update your production server directly. Copy the entire server directory to a separate location, apply the update there, and start it up. This lets you catch problems without affecting live players.

1. Copy the server directory: cp -r /srv/minecraft /srv/minecraft-test-121
2. Replace the jar in the test copy with the 1.21 jar.
3. Update Java path in the test startup script.
4. Start the test server on a different port.
5. Join and check: Do worlds load? Do plugins start without errors? Are items intact? Do commands work?
6. Read the console log carefully. Yellow warnings might be fine. Red errors need attention.

Handling World Format Changes

Minecraft's DataFixerUpper (DFU) system automatically converts world data from older formats to newer ones when you load a world on a new version. This happens on first load and can take a while for large worlds. During this process:

• Players will experience longer chunk load times the first time they visit old areas.
• New biomes, blocks and structures only generate in unexplored chunks. Existing terrain stays the same except for data format upgrades.
• Some blocks might behave differently if Mojang changed their properties. Check the Minecraft wiki's version history for 1.21 to see what changed.

If you want new 1.21 content in already-explored areas, you will need to trim those chunks using a tool like MCASelector before updating. This forces them to regenerate with new world generation. Only do this for areas you are willing to lose, player builds in trimmed chunks will be deleted.

What Typically Breaks

• Removed or renamed items/blocks: If Mojang removed an item or changed its ID, existing instances might turn into air or a different block. This is rare in minor versions but can happen in major ones.
• Changed NBT tags: Plugins that store custom data in item NBT may find their data missing or in a different format. Custom items from plugins like ItemsAdder or Oraxen need updated configs.
• Plugin API changes: Paper and Spigot change their APIs between major versions. Plugins compiled against 1.20 API classes may throw NoSuchMethodError or ClassNotFoundException on 1.21.
• Recipe changes: Custom recipe plugins need updating if Mojang added new recipes that conflict with custom ones.

The Update Order That Works

After testing on a copy, here is the order for your production server:

1. Announce maintenance to players. Give at least 30 minutes warning.
2. Stop the server cleanly, do not force-kill the process.
3. Take a final backup (yes, another one).
4. Replace the server jar with the 1.21 version.
5. Update Java path in startup script if needed.
6. Update plugins that have 1.21-ready versions. Remove or disable plugins that are confirmed broken.
7. Start the server.
8. Monitor the console for errors. Join and test core functionality.
9. Open to players only after you are confident things are working.

Rollback Plan

If the update goes badly, persistent crashes, major data loss, critical plugins completely non-functional, you need to roll back. This means:

1. Stop the broken 1.21 server.
2. Delete or rename the 1.21 server directory.
3. Restore your pre-update backup.
4. Restore the database backup if you changed database-backed plugins.
5. Start the old version.

Warning: If any player loaded new chunks or obtained new 1.21 items before you rolled back, that data will be lost or corrupted. This is why you should test thoroughly before opening to players. See our guide on downgrading server versions for the full picture on what is and is not reversible.

Need hosting for your network? Astroworld Hosting offers NVMe SSD, Pterodactyl panel, and DDoS protection. See features , plans from €6.39/mo.