Migrating from Paper & updates

Move an existing Paper server to NusaSpigot, update to a newer release, and know what to check before you switch back.

On this page

NusaSpigot is a drop-in Paper fork, so your existing worlds, server.properties, paper-global.yml, spigot.yml and plugins/ folder carry over as they are. This page shows the safe order of steps.

Moving from Paper to NusaSpigot

  1. Stop the server cleanly with stop and wait until the process has fully exited.
  2. Make a full backup of the whole server folder (worlds, plugins/ and config files) and keep a copy outside the live folder.
  3. Copy NusaCore.jar and nusa-license.properties from your download into the server folder.
  4. Point your start script or panel to NusaCore.jar instead of the Paper JAR. The start commands are in Quick start & installation.
  5. Start the server. Choose your Minecraft version when NusaCore asks. NusaSpigot creates nusa-global.yml and nusa-world.yml with safe defaults next to your Paper configs.
  6. Check health with nusa status and nusa doctor in the console.

Use the same Minecraft version as your old Paper server (for example 1.21.11). Moving to a newer Minecraft version at the same time is a separate step; test it on a copy first.

Updating NusaSpigot

If you already run NusaCore, updating is one step:

  1. Restart the server.
  2. NusaCore downloads and verifies the newest release for your Minecraft version by itself.

Your existing configuration values are kept. New settings that are missing from your files use their safe defaults. A release note may also recommend replacing NusaCore.jar with the newer one from the download page; do that while the server is stopped.

Coming from an older build started directly

If you still start an older NusaSpigot build directly as a server JAR (for example NusaSpigot-v1.2-1.21.11.jar), switch to NusaCore:

  1. Stop the server and make a backup.
  2. Put NusaCore.jar and nusa-license.properties from the current download into the server folder.
  3. Change the start command to java -jar NusaCore.jar --nogui. Keep your memory flags.
  4. Start the server and choose your Minecraft version when asked.

Your worlds, plugins and nusa-global.yml stay as they are.

Moving a license to Minecraft 26.2

A license is locked to one Minecraft version when it is first used. To move an existing license to 26.2, open a support ticket. Remember that 26.2 needs Java 25, and plugins that use server internals with Spigot mappings need a 26.2 update from their author. See Plugin compatibility.

Important: region compression and switching back

feature-flags.region-file-compression is true by default. What this means for you:

  • Existing Paper chunks load normally. Nothing is converted all at once on startup.
  • Newly saved chunks use Zstandard (Zstd) compression. Plain Paper or vanilla cannot read those chunks directly.
  • Still evaluating? If you might go back to plain Paper without restoring your backup, turn it off before players join:
feature-flags:
  region-file-compression: false

Keep your pre-migration Paper backup until you are happy with the switch.

Next steps

Nusa product documentation · NusaSpigotPaper fork · Java 21 / 25

Loading the index…