Migrate from Paper or another fork

Prepare staging

Staging is a separate private test copy. Use a different folder and port. Prevent copied plugins from sending production notifications or writing to the same production database unintentionally.

1. Record Minecraft, Java, server, plugin, and dependency versions.
2. Run stop on the original server and wait for exit.
3. Make a complete backup and retain the old JAR.
4. Copy the required files to staging, adjusting ports and external plugin connections there.
5. Select the matching Nusa release. Test a Minecraft-version upgrade separately from a fork migration where possible.

Keep the required data

Copy every world/dimension, plugin JARs and data, Paper/Bukkit/Spigot configuration, properties, whitelist, operators, permissions, and bans. Database plugins need a coordinated database backup too.

Nusa creates its config files when missing. Read zstd rollback compatibility before Nusa saves the old world. To select Paper’s writer from the first staging startup:

feature-flags:
  region-file-compression: false

Other defaults still apply. This does not convert chunks already written as Nusa zstd.

Verify the migration

Read nusa doctor, then test login, permissions, inventory, teleport, claims, economy, and important plugin workflows. Check dimensions, save, stop, and reopen. Test mobs, hoppers, tracking, and custom items.

Spigot and other forks may differ in world layout and behavior. Follow the applicable upstream migration procedure, then test Nusa independently. Preserved APIs do not certify every NMS/reflection plugin.

If testing fails, stop staging and restore the copy. After success, schedule downtime and repeat with a fresh production backup using the update procedure.