Nexardo

Minecraft Field guide

How to Safely Update a Paper Minecraft Server: Build Automation and Plugin Safety

How to safely update a Paper Minecraft server: querying builds via REST API v2, validating SHA256 checksums, establishing rollback checkpoints, and plugin safety.

EugenePublishedUpdatedReading time3 min
How to Safely Update a Paper Minecraft Server: Build Automation and Plugin Safety

Regularly updating the Paper server software is a vital maintenance task for stability, security patching, and upstream Mojang bug fixes. The PaperMC team publishes dozens of automated builds weekly, refining network routines and patching vanilla engine vulnerabilities. However, downloading new .jar releases blindly without snapshotting state risks plugin breakages, corrupt chunk formatting, and irreversible world data loss.

This guide covers the safe update lifecycle for Paper servers: querying verified builds via the PaperMC REST API v2, automating downloads with Bash scripts, validating cryptographic checksums, and troubleshooting post-update plugin regressions.

Understanding PaperMC Version Architecture and Update Risks#

Paper distributes server software as Paperclip executable jars that patch vanilla Minecraft binaries at runtime. Releases follow the standard semantic convention: <Minecraft_Version>-<Build_Number> (e.g., 1.21.1-118).

Engine updates fall into two risk categories:

  1. Incremental Patch Builds (Minor Builds): Upgrading from build 80 to build 115 within Minecraft 1.21.1. These builds carry negligible risk: they address targeted bugs and retain full Bukkit/Spigot API backward compatibility.
  2. Major Engine Version Transitions: Upgrading across versions (e.g., 1.20.4 to 1.21.0). High risk: Mojang regularly alters NBT data serialization schemas across chunk storage files. Once a world is loaded on a newer engine build, it cannot be downgraded without an earlier cold backup; older builds treat newer chunk schemas as corrupt and regenerate them from scratch.

Establishing a Rollback Checkpoint: World and Plugin Backups#

Always halt the active server daemon prior to swapping binary files:

bash
sudo systemctl stop minecraft
sudo systemctl status minecraft --no-pager

Generate an isolated compressed archive containing active world regions, plugins, and configurations:

bash
BACKUP_DIR="/opt/minecraft/backups"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
mkdir -p "$BACKUP_DIR"

tar -czf "$BACKUP_DIR/pre_update_${TIMESTAMP}.tar.gz" \
  -C /opt/minecraft world world_nether world_the_end plugins config

Verify that the archive exists and shows expected size:

bash
ls -lh "$BACKUP_DIR/pre_update_${TIMESTAMP}.tar.gz"

Using an automated server management panel, system snapshots and rollback checkpoints are generated automatically prior to deploying newer server builds.

Fetching Verified Builds via the PaperMC REST API v2#

Rather than downloading jars manually through web browsers, query the official PaperMC public REST API v2 programmatically.

Identify the latest stable build identifier for your target release (such as 1.21.1):

bash
MINECRAFT_VERSION="1.21.1"
API_URL="https://api.papermc.io/v2/projects/paper/versions/${MINECRAFT_VERSION}"

LATEST_BUILD=$(curl -s "$API_URL" | jq '.builds[-1]')
echo "Latest available Paper build: $LATEST_BUILD"

Download the jar package directly from the PaperMC CDN:

bash
DOWNLOAD_URL="https://api.papermc.io/v2/projects/paper/versions/${MINECRAFT_VERSION}/builds/${LATEST_BUILD}/downloads/paper-${MINECRAFT_VERSION}-${LATEST_BUILD}.jar"

curl -o "/opt/minecraft/paper-${MINECRAFT_VERSION}-${LATEST_BUILD}.jar" "$DOWNLOAD_URL"

Verify the downloaded file's SHA256 checksum against the API manifest:

bash
EXPECTED_SHA=$(curl -s "https://api.papermc.io/v2/projects/paper/versions/${MINECRAFT_VERSION}/builds/${LATEST_BUILD}" | jq -r '.downloads.application.sha256')
ACTUAL_SHA=$(sha256sum "/opt/minecraft/paper-${MINECRAFT_VERSION}-${LATEST_BUILD}.jar" | awk '{print $1}')

test "$EXPECTED_SHA" = "$ACTUAL_SHA" && echo "Checksum verified successfully!"

Atomic Symlink Switching and File Permissions#

Maintain an atomic symbolic link paper.jar pointing to the active build:

bash
cd /opt/minecraft
ln -sf "paper-${MINECRAFT_VERSION}-${LATEST_BUILD}.jar" paper.jar

Ensure ownership belongs to the dedicated service account:

bash
sudo chown -R minecraft:minecraft /opt/minecraft
sudo chmod 644 /opt/minecraft/paper*.jar

Start the systemd service and monitor initialization output:

bash
sudo systemctl start minecraft
sudo journalctl -u minecraft -f --no-pager

Diagnosing Post-Update Plugin Incompatibilities#

During server startup, watch for initialization warnings:

  1. UnsupportedClassVersionError: The new Paper build requires an updated Java runtime (such as OpenJDK 21). Verify Java version compatibility with java -version.
  2. PluginClassLoader or NoSuchMethodError: An outdated plugin calls an obsolete Bukkit method removed in the new build. Temporarily rename the plugin jar to .disabled and check Modrinth or SpigotMC for patches.
  3. Emergency Rollback: If an essential plugin fails, redirect the paper.jar symlink back to the previous stable build and restart:
    bash
    ln -sf paper-previous-stable.jar paper.jar
sudo systemctl restart minecraft

Sources#