Known issues and limits

Check plugin compatibility and the known limits of NusaGate before you install it or report a problem.

On this page

Read this page before you migrate a network to NusaGate or report a problem. It lists what works, what does not, and the settings that most often surprise new owners.

Plugin compatibility

NusaGate is built on official PaperMC Velocity and uses the normal Velocity plugin API.

  • Velocity plugins work. Popular Velocity plugins such as LuckPerms, ViaVersion, Geyser, Floodgate, LimboAPI, TAB, LiteBans and LibertyBans are supported.
  • BungeeCord-only plugins do not load. A plugin made only for BungeeCord or Waterfall (it has a bungee.yml and no velocity-plugin.json) cannot be loaded directly. You need its Velocity version or a Velocity alternative.
Old BungeeCord pluginUse on NusaGate instead
BungeeGuardVelocity's built-in modern forwarding: player-info-forwarding-mode = "modern" in velocity.toml.
AuthMeBungeeAuthMeVelocity or LimboAuth.
BungeeTabListPlusTAB, Universal or Velocity edition.
ServerListPlus (BungeeCord-only build)A ServerListPlus build that supports Velocity, or MiniMOTD for Velocity.
AdvancedBan (old BungeeCord build)LibertyBans or LiteBans for Velocity.
Your own BungeeCord pluginPort it to the Velocity API.

Linux-only features

Some PRO modules work at the operating-system level: native TCP checks, country blocks at firewall level, and the bridge helper that manages them. They need:

  • a Linux host with the required firewall tools (ipset and iptables);
  • the separate privileged bridge helper, running next to the proxy.

On Windows, macOS or a standard container without network admin rights (for example a typical Pterodactyl panel), these modules are skipped automatically. All other protection keeps running as normal.

Do not run the proxy as root

On Linux, NusaGate refuses to start when the proxy runs as root. Run it as an ordinary user such as minecraft or nusagate. If you use the Linux bridge helper, give the extra network rights only to that separate helper, never to the proxy itself.

Joining with an IP address is refused

By default, anti-bot.dns-check.block-direct-ip is true. Players who join with a raw IP address instead of your domain are refused with a message asking them to use the official address. Joining through localhost still works for local tests.

If you test a staging server through its IP address, set block-direct-ip: false and run /ng reload. Turn it back on before you open to the public.

Many players on one IP address

Schools, internet cafes and some mobile networks put many players behind one public IP address. The defaults allow several players per IP, but very busy shared connections can hit per-IP limits. Review the per-IP limits in anti-bot, and in PRO add those addresses to Account Guard's exempt-ips. The PRO Packet Firewall skips its per-IP limits when the proxy sits behind a PROXY-protocol frontend.

Anti-VPN without an API key (PRO)

Without an API key for at least one provider, the Anti-VPN module cannot confirm a VPN and lets everyone through. The Country Guard uses the same providers, so it also needs at least one of them configured. Provider fees and quotas are separate from NusaGate.

Bedrock players

Bedrock players need the Velocity editions of Geyser and Floodgate, installed on the proxy. NusaGate detects them and uses its Bedrock fast paths.

ViaVersion add-ons

The built-in ViaVersion lets newer clients join older supported servers. ViaBackwards and ViaRewind are separate add-ons and are not installed automatically. See Built-in ViaVersion.

DDoS protection

NusaGate filters connections inside the proxy. It cannot recover a network link that is already full. Keep your host's DDoS protection and a firewall in front of your backend servers.

Next steps

Nusa product documentation · NusaGateFree & PRO editions

Loading the index…