How to Safely Update a Paper Minecraft Server

Know which update you are making

A routine Paper build update and a jump to a new Minecraft release are not the same maintenance job. A build update stays on the same game version and usually concentrates risk in the server JAR and plugins. A game-version upgrade can also change Java requirements, plugin support, configuration defaults and world data. Write down the current Minecraft version, Paper build, Java runtime and plugin versions before downloading anything. That inventory is the baseline you need to test and, if necessary, restore.

Read Paper's update notes and the release pages for every plugin that stores important data or changes world behavior. Permissions, claims, economy, inventories, cross-server chat and map plugins deserve particular attention because a clean server boot does not prove their data still behaves correctly. If a required plugin has no release for the target Minecraft version, postpone the game-version upgrade or test an explicitly supported alternative. Hope is not a compatibility plan.

Choose one exact target rather than asking an updater for whatever is newest at restart time. Paper's downloads service identifies stable builds and publishes a SHA-256 checksum for each download. Record the target version, build and checksum in the maintenance notes. Paper advises using stable builds in production and warns against unattended automatic updates because plugin conflicts can need immediate human judgment.

Create a backup you can actually restore

Stop the server cleanly before copying its files. Paper's troubleshooting guidance warns that changing server files while the process is running can corrupt them; a panel that says “stopping” is not finished. Wait until the console confirms shutdown and the Java process has exited. Paper's own update checklist names the world folders, server configuration, plugin configuration and plugin JARs as the essential backup set. For a dependable rollback, archive the entire server directory when storage allows it.

Keep the backup outside the live server directory and give it a timestamp plus the Minecraft, Paper and Java versions. Include the startup script or panel command, server.properties, Paper/Bukkit/Spigot configuration, the plugins directory, whitelist, operators, bans and every world named by level-name or a world-management plugin. If plugins use an external database, snapshot that database at the same maintenance point or document how its state will be reconciled. A world archive and a newer economy database are not one consistent restore point.

Verification is what turns an archive into a backup. List or open the archive, confirm the expected world region files and plugin data are present, and compare its size with the live directory. Best of all, restore it into an isolated directory and start the old stack once. Keep several rolling backups in a separate location instead of overwriting yesterday's only copy. A host-provided snapshot is useful, but you still need to know its scope, retention and restore procedure before the update window begins.

• Record current Minecraft, Paper, Java and plugin versions before shutdown.
• Stop cleanly and wait for the Java process to exit before archiving files.
• Back up all worlds, configuration files, plugin JARs and plugin data together.
• Store the archive away from the live directory and test that it can be restored.

Check Java and plugin compatibility

Confirm the Java requirement from Paper's current getting-started table for the exact target release. At the time of this guide, Paper lists Java 21 for Minecraft 1.20 through 1.21.11 and Java 25 for 26.1 and later. Do not assume the runtime selected in an interactive shell is the one used by a service, container or hosting panel. Run java -version through the same startup environment that launches the server, and make the Java change part of the staging test.

For plugins, use first-party release pages such as Paper's Hangar repository, the author's Modrinth project or the project's own GitHub releases. Match both the target game version and the Paper-compatible platform. Paper plugins execute with unrestricted access to the server machine, so an update is also a supply-chain decision: download only from a source you trust, preserve checksums where the publisher provides them and never substitute a similarly named file from an aggregator.

Update dependencies and their dependants as one tested set. Paper documents a plugins/update folder that swaps queued plugin JARs during restart without replacing live files, but this convenience does not remove the need for compatibility review. Avoid leaving two versions of the same plugin in the plugins directory; Paper identifies duplicate plugin names as an unsupported condition. Preserve old JARs inside the offline backup, not beside active JARs where the loader might find them.

Rehearse on an isolated staging copy

Clone the stopped backup into a separate staging directory or temporary server. Use the same Java version, startup flags and memory limit planned for production. Prevent players from reaching it, bind it to a different port, and disable outbound integrations that could send real webhooks, charge an economy service or write to the production database. The point is to exercise the real upgrade against representative data without creating a second writer to live systems.

Install the chosen stable Paper JAR and the reviewed plugin set, then start staging while watching from the first log line. Resolve unsupported Java errors, missing dependencies, duplicate plugins, failed data migrations and severe warnings before joining. Paper's plugin guide points to logs/latest.log for the most recent startup record and recommends confirming that plugins are enabled. Save the complete log with the maintenance notes; a quiet console five minutes later can hide an error that appeared only during initialization.

Join with a test account and exercise state, not just connectivity. Visit the overworld, Nether and End; load old and newly generated chunks; check inventories, advancements, portals and command permissions. Test claims, shops, economy balances, scheduled tasks and backups according to the server's plugin set. Restart staging a second time to catch migrations that appeared successful only on their first boot. If any critical behavior is uncertain, stop here and keep production on the known-good version.

Run a controlled production update

Schedule a maintenance window with enough time to validate or restore—never just enough time to restart. Announce the shutdown, remove player access, run the normal save process, stop the server and confirm it has exited. Take the final verified backup after that shutdown. Paper explicitly says not to replace Paper or plugin JARs in a running server, even when the filename looks unused.

Upload the selected Paper JAR, verify its checksum and make the startup command point to that exact file. Either replace the offline JAR using the same configured filename or change the start command to the new versioned filename; Paper documents both approaches. Apply only the plugin versions from the staging run. Changing unrelated server settings in the same window makes failures harder to attribute and expands the rollback surface.

Start the server with an administrator present. Read the whole startup sequence, confirm the reported Minecraft, Paper and Java versions, and verify that each expected plugin enables. Do not reopen access because the process reached “Done.” Run the same short acceptance test used in staging first. If the console shows a serious migration, dependency or data error, stop cleanly and choose rollback before players create new state on the upgraded server.

• Freeze player writes, stop cleanly and take the final consistent backup.
• Deploy the exact staged stable JAR and plugin set; verify the download checksum.
• Watch startup from the beginning and confirm versions plus plugin enablement.
• Complete acceptance tests before reopening the server to players.

Validate performance and player data

After reopening, monitor the first real workload instead of treating the maintenance as finished. Watch exceptions, tick time, memory pressure, player disconnects and plugin-specific warnings through at least one busy period. Compare against the baseline from before the update. A small burst of work while chunks or caches warm may be explainable; sustained regressions need investigation rather than a larger memory allocation by reflex.

Ask moderators to check the workflows players notice first: joining, teleporting, claiming, trading, inventories, permissions and scheduled restarts. Confirm that a new post-update backup completes and that its archive contains the expected data. For a deeper performance baseline, use the measurements in the Minecraft server lag guide at /blog/minecraft-server-lag-fix-guide rather than relying on player frame rate or a single TPS reading.

Keep the maintenance log with the target checksum, backup identifier, plugin set, start and finish times, tests and any warnings accepted. This record makes the next update faster and gives support staff reproducible facts. More operational guides are collected at /blog, and if monitoring shows a genuine capacity limit after the software is healthy, compare scalable hosting options at /pricing.

Roll back without mixing old and new state

Define rollback triggers before maintenance: a required plugin fails, worlds do not load correctly, player data is missing, the server crashes, or performance remains materially worse after warm-up. When a trigger occurs, stop the upgraded server and preserve its logs for diagnosis. Do not repeatedly restart it and hope a migration repairs itself; each start can create more changed state and make a clean decision harder.

Restore the complete pre-update set into an empty isolated server directory: world data, configuration, plugin JARs, plugin data, the old Paper JAR and the compatible Java/startup settings. Restore any external database to the matching point. Never point an older runtime at the already-upgraded live directory as a shortcut. Bringing back the coherent old stack is safer than combining a new world or plugin schema with old code.

Validate the restored server privately before reopening it, then communicate that activity after the backup timestamp may need to be replayed or reconciled. Once service is stable, reproduce the failure in staging using the captured logs. A postponed update with a tested restore is a successful safety outcome; it is far better than converting an uncertain upgrade into permanent world or player-data loss.