Prepare the recovery point before starting the new Paper build. Once the new version has modified the world or plugin data, putting the old JAR back is not a complete rollback. Keep the old program and its pre-update data together, then update during one planned maintenance window.
These steps use the Ubuntu Paper installation: service minecraft, account minecraft, directory /srv/minecraft. You need sudo, SSH and an independent backup destination. This is a Paper update, not a conversion from Fabric, Forge, Bedrock or a proxy network.
Decide whether you are changing a build or the game version#
A newer Paper build for the same Minecraft release and a move to another Minecraft release have different compatibility risks. Write down both the game release and Paper build you are leaving, and the specific pair you intend to install. A moving latest URL is a poor maintenance record.
Check current Paper runtime requirements before choosing the target: on October 12, 2026, the table recommends Java 21 for 1.20–1.21.11 and Java 25 for 26.1+. Do not infer the required runtime from an old tutorial or the Java executable used by your SSH shell.
For each plugin, check its publisher's supported game/Paper release, required dependencies and migration notes. Include world generators, inventory/permissions plugins and plugins with external databases. If an essential feature has no compatible release, defer the game-version migration or choose a documented replacement and test its data conversion separately. Removing an essential plugin simply to make the startup log quieter changes the server players receive.
Record the actual installation#
On the VPS, inspect the unit and existing files:
sudo systemctl cat minecraft
sudo systemctl show minecraft -p ExecStart -p WorkingDirectory -p User
sudo -u minecraft /bin/bash -c 'cd /srv/minecraft && sha256sum -c paper.jar.sha256'
sudo ls -la /srv/minecraft/plugins
sudo tail -n 100 /srv/minecraft/logs/latest.log
df -h /srv /var/backups
Record the Java executable from ExecStart, then run that exact executable with -version. Save a private copy of the unit and any drop-ins, plugin versions, the world name and external database restore instructions. Read logs for the actual running build; a filename does not establish its identity.
Inspect any existing plugins/update directory: pending replacements may apply at the next start. Account for them in the plan before creating the baseline. The Paper plugin guide explains duplicate JAR and dependency failures. Plan explicit replacements so only one intended version of each plugin remains.
Leave enough space for a complete archive, transfer staging, a restored copy and the preserved failed directory. If your backup needs external database data, arrange a consistent database backup while game writers are stopped. A directory archive cannot do this automatically.
Select trusted files and rehearse the change#
On your computer, download the specific build from Paper's official downloads. Keep its original filename and build in your note; name the upload copy paper-next.jar. Use each plugin's trusted publisher release, not a repackaged bundle from an unfamiliar download site.
Before production maintenance, rehearse with an isolated copy and the target Java runtime. Keep test players and external plugin connections separate from production. Test the world generator, known builds, inventories, permissions and commands your group actually uses. Opening the new JAR successfully does not validate those features. If a migration is documented as one-way, the rehearsal copy is disposable; retain the unchanged baseline.
Prepare private transfer staging on the VPS:
install -d -m 700 "$HOME/minecraft-transfer"
chmod 700 "$HOME/minecraft-transfer"
Upload from your computer:
sha256sum paper-next.jar
scp paper-next.jar SSH_USER@VPS_IP:minecraft-transfer/paper-next.jar
Replace the SSH account/address and add -P YOUR_SSH_PORT for a custom port. On the VPS, compare sha256sum "$HOME/minecraft-transfer/paper-next.jar" with your local result. This checks transfer integrity; the trusted download source establishes provenance.
Restrict admission before the next start#
Before stopping the old build, record the original allowlist and operator access policy in your private note. As an operator in the game, enable the allowlist, add your actual test administrator, and remove every ordinary account for the maintenance window. Replace the names below and repeat removal for the whole ordinary-player list:
/whitelist list
/whitelist on
/whitelist add TestAdmin
/whitelist remove PlayerToExclude
Only approved test administrators should retain operator access during acceptance; revoke any other operator access with /deop AccountName and record its previous permissions. Do not assume a whitelist excludes privileged administrators. Use server commands to manage these lists as described in Paper's data-file reference, rather than inventing account UUIDs.
After stopping below, check server.properties: keep online-mode=true, and set white-list=true and enforce-whitelist=true before starting the updated build. Replace existing keys, not append duplicates. These Paper settings preserve account authentication and enforce selected admission. The baseline will contain the temporary maintenance access policy; keep the separately recorded original policy for reopening after acceptance. If you cannot establish test-only admission, postpone the first updated start.
Enter maintenance and keep Paper stopped#
Notify players, pause other jobs that might start the server, then on the VPS:
sudo systemctl stop minecraft
sudo journalctl -u minecraft -n 80 --no-pager
sudo systemctl show minecraft -p ActiveState -p MainPID -p Result
Proceed only after normal saving, inactive, PID 0 and a successful stop result. If shutdown timed out or storage failed, resolve that first. The systemd service manual describes forced termination after a stop timeout; a dead process alone is not a clean save.
Make a pre-update baseline, with Paper still stopped:
(
set -e
test "$(sudo systemctl show minecraft -p ActiveState --value)" = inactive
test "$(sudo systemctl show minecraft -p MainPID --value)" = 0
test "$(sudo systemctl show minecraft -p Result --value)" = success
sudo install -d -m 700 /var/backups/minecraft
MC_BASELINE="/var/backups/minecraft/pre-update-$(date +%F-%H%M%S).tar.gz"
sudo test ! -e "$MC_BASELINE"
sudo tar -C /srv -czf "$MC_BASELINE.partial" minecraft
sudo chmod 600 "$MC_BASELINE.partial"
sudo tar -tzf "$MC_BASELINE.partial" > /dev/null
sudo mv "$MC_BASELINE.partial" "$MC_BASELINE"
sudo install -o "$(id -un)" -m 600 "$MC_BASELINE" "$HOME/minecraft-transfer/backup.tar.gz"
cd "$HOME/minecraft-transfer"
umask 077
sha256sum backup.tar.gz > backup.tar.gz.sha256
)
Stop on any error; do not accept a .partial file. Complete coordinated external database copies now. On your computer, retrieve the baseline into a fresh dated private directory. The block stops if either transfer fails, so a stale pair cannot substitute for this attempt:
(
set -e
umask 077
MC_UPDATE_COPY="$(mktemp -d "$HOME/minecraft-pre-update-$(date +%F-%H%M%S).XXXXXX")"
chmod 700 "$MC_UPDATE_COPY"
cd "$MC_UPDATE_COPY"
scp SSH_USER@VPS_IP:minecraft-transfer/backup.tar.gz ./backup.tar.gz
scp SSH_USER@VPS_IP:minecraft-transfer/backup.tar.gz.sha256 ./backup.tar.gz.sha256
sha256sum -c backup.tar.gz.sha256
pwd
)
Record the printed destination with the versions and maintenance date. Keep the backup.tar.gz and backup.tar.gz.sha256 basenames unchanged in that directory, since the checksum manifest names the archive. After both transfers and verification succeed, use the backup and restore guide to inspect this selected pair and rehearse restoration. Keep this pre-change recovery point even if you create newer backups afterwards.
Do not restart Paper between this baseline and the update. Otherwise players can create changes that your pre-update copy does not contain, and the recovery point is no longer the state immediately before migration.
Replace the chosen artifacts offline#
If the target needs a different Java runtime, install it first, pin its verified absolute executable in the unit and retain the old unit/runtime information for rollback. After editing the unit, run sudo systemctl daemon-reload. Do not change Java globally for unrelated applications.
Apply the planned compatible plugin replacements while stopped, following their own migration instructions. Preserve their prior files in the baseline and coordinate external schema changes. Then install the selected Paper JAR on the VPS:
(
set -e
test "$(sudo systemctl show minecraft -p ActiveState --value)" = inactive
test "$(sudo systemctl show minecraft -p MainPID --value)" = 0
test -s "$HOME/minecraft-transfer/paper-next.jar"
sudo install -o minecraft -g minecraft -m 640 "$HOME/minecraft-transfer/paper-next.jar" /srv/minecraft/paper.jar
sudo -u minecraft /bin/bash -c 'cd /srv/minecraft && sha256sum paper.jar > paper.jar.sha256'
sudo systemctl start minecraft
sudo journalctl -u minecraft -n 120 --no-pager
)
These are original shell steps for this installation. Paper's update guide requires offline replacement and startup inspection. test -s checks only that the upload is not empty; it does not validate a JAR or authorize its source.
Accept the update based on game behavior#
Watch startup through Done, identify the intended build and investigate plugin errors. Then join with an approved test account and matching client and check the agreed acceptance list: world/landmarks, inventories, permissions, dimension travel and essential plugin actions. Let the server save, perform a controlled restart and check that those results persist. Only after acceptance, restore the recorded original allowlist/operator policy through the server's administration controls and announce reopening; keep authentication enabled.
| Observation | Decision |
|---|---|
| Java class-version failure | Check the exact ExecStart runtime against the selected branch |
| Plugin dependency or duplicate-name failure | Fix the planned plugin set while stopped, or restore the baseline |
| Unexpected new world | Stop; inspect working directory, level-name and original world files |
| Startup succeeds but essential behavior breaks | Keep player access closed and choose repair or full rollback |
| Lag appears with the new version | Capture evidence using the spark diagnosis guide; do not randomly rewrite JVM flags |
For browser-based administration of your own VPS, Nexardo can be considered separately. It does not automatically adopt this manual service or make an incompatible plugin migration reversible.
Roll back the binary and its matching data#
Paper's developer explanation describes why world downgrading is unsupported: version conversion changes saved data. Treat rollback as restoration of the complete pre-update state, including its old JAR and plugins. Do not point the old binary at a world the new release has already saved.
Stop the updated service to end any restart loop. Preserve its directory and relevant logs; it may contain evidence or post-update player progress. Follow the staged restoration procedure in the backup guide using this baseline's backup.tar.gz and checksum. Restore the old service configuration/runtime and coordinated external database state before starting it. If a plugin's database cannot be returned to the matching point, resolve that gap before treating rollback as complete.
Players lose changes made after the baseline. Say so before reopening access. The baseline retains maintenance admission: repeat the real-world acceptance checks with the approved test accounts before restoring the original access policy. Keep both the baseline and failed update copy until the incident is understood. A successful archive checksum is one check in that process, not proof of a playable recovery.
