Troubleshooting & FAQ

Fast fixes for startup errors, license activation, TPS drops, Bedrock rubberbanding, and common server questions.

On this page

Most server issues can be solved in under two minutes using the checks below.

Quick fixes for common issues

Server refuses to start (UnsupportedClassVersionError)

Your machine or Pterodactyl container runs a Java version that is too old. Minecraft 1.21.11 needs Java 21 or newer, and Minecraft 26.2 needs Java 25 or newer. Switch your panel Docker image, or check that java -version shows the right version.

Startup stops with IllegalArgumentException in NusaConfigurations

A value edited in nusa-global.yml has the wrong type or is outside its allowed range (for example, writing text where a number is expected, or setting resume-tps lower than minimum-tps). Read the exact key name shown in the error message and check its allowed range in the All settings reference.

License validation fails on startup

  1. Open nusa-license.properties and check the key has no extra spaces or quotes. To enter it again, set renew-license-input=true in nusacore.properties and restart (see NusaCore & license).
  2. Check that your host allows outbound HTTPS and that the system clock is correct (NTP).
  3. Read the console message. If it says the license was refused or the version is not included, open a support ticket instead of retrying.

The server says to start it with NusaCore

Licensed builds only start through NusaCore. Change your start command or panel Startup JAR to NusaCore.jar (see Quick start & installation).

I chose the wrong Minecraft version

The version choice is locked to your license, so you cannot change it yourself. Open a support ticket and we will reopen the choice. NusaCore asks again on the next start.

Bedrock (Geyser) players still rubberband on blocks

  1. Confirm bedrock-optimization.enabled: true in nusa-global.yml.
  2. If you run Geyser behind Velocity/BungeeCord without Floodgate installed on the backend server, make sure bedrock-optimization.username-prefix matches your Bedrock player prefix (default '.'), or install Floodgate on the backend so XUID UUID detection works automatically.
  3. Check if a third-party anti-cheat plugin (Grim, Vulcan, Matrix) is causing the setback rather than vanilla movement checks.

TPS drops when players explore or farm

  1. Run nusa status to check MSPT and Heap usage. If Heap is stuck above 90%, increase -Xms / -Xmx or lower view-distance / simulation-distance in server.properties.
  2. Pre-generate your world with nusa pregen 128 world (radius in chunks) so exploration reads existing chunks instead of generating terrain live. See World pre-generation.
  3. Run nusa lagchunks start 30 to see which chunks and plugins cost the most tick time. See Lag diagnostics & auto-tune.

Frequently Asked Questions (FAQ)

Do all Paper and Spigot plugins work on NusaSpigot?

Yes. NusaSpigot preserves every Paper, Spigot, and Bukkit 1.21.11 API signature and keeps one real main server thread, so standard plugins run without modification.

Why was my idle TPS around 19.x on older versions on Windows?

Windows lowers its default OS sleep timer resolution to ~15.6 ms when idle. Since NusaSpigot v1.2, the server automatically calibrates high-resolution timer pacing so idle servers stay locked at 20.00 TPS on both Windows and Linux.

How do I update NusaSpigot?

Restart the server. NusaCore downloads the newest release for your Minecraft version by itself. What changed is listed in the Release notes.

Does NusaSpigot need an extra port open for the Cloud Panel?

No. /nusa link uses an outbound HTTPS connection initiated by your server, so it works behind NAT, home routers, and standard Pterodactyl allocations without opening extra ports.

Why do config changes require a restart instead of /nusa reload?

Worker thread pools, Netty pipeline handlers, and region compression codecs are wired at startup so they never race with active player connections or live chunks. A clean stop and start keeps world data 100% safe.

Nusa product documentation · NusaSpigotPaper fork · Java 21 / 25

Loading the index…