Troubleshooting

Fix the most common NusaPack problems, from Bedrock players seeing vanilla items to menus that look shifted.

On this page

Most NusaPack problems have a quick fix. Start with the two commands below, then look up your symptom in the table.

Start with two commands

  1. /npb check shows the versions in use and checks the usual reasons Bedrock players still see vanilla items, each with its fix.
  2. /npb report errors lists every problem from the last conversion, with the reason.

/npb check looks for these common causes:

  • Geyser is missing, or enable-custom-content is false in Geyser's config.
  • force-resource-packs is false in Geyser's config, so players can refuse the pack.
  • nusapack-geyser.jar is missing from plugins/Geyser-Spigot/extensions/, or installed but not loaded yet.
  • There are two copies of a NusaPack jar.
  • There is no pack yet, or the pack is waiting for a restart.

Common problems

SymptomWhat to do
Bedrock players see nothing newRead the last line of /npb convert. "Live for Bedrock" means players must rejoin; "Installed · restart the server once" means restart once.
"Conversion rejected"Run /npb report errors and fix the listed models or textures. Or run /npb config conversion_mode partial to ship everything that did convert.
"untested version" warningThe conversion continues. If something looks wrong, report it together with the plugin version.
A plugin is listed under "Left out or adjusted"The line gives the reason: no built pack yet (build it in that plugin, or set its path under source-packs in sources.yml), a protected or obfuscated pack, or an item list that cannot be read.
A glyph is too big or too smallSet its size in glyphs.yml (copy the entry from glyphs-auto.yml), convert, then rejoin.
A custom menu is a plain chest on BedrockRun /npb gui scan, or open the menu and run /npb gui capture. Then convert and rejoin.
A chest menu looks shiftedRun /npb gui tune <id> offset_x <px> or offset_y <px>, then convert and rejoin.
Furniture bridge disabledRead the log line. Furniture display needs Minecraft 1.21.4.
"NusaPack Bridge is locked", or the plugin is disabled at startupLicensed builds only. Read the license lines in the console, fix the key in nusa-license.properties, and restart.
/npb convert stops before convertingThe disk is too full for the result. The message shows how much space is free and how much is needed; free up space and run it again.

When a restart is needed

Geyser registers custom items, blocks and mobs only while it starts. That is a Geyser rule, not a NusaPack one. These changes therefore need one server restart:

  • the first conversion on a server
  • adding or removing custom items, custom blocks or mobs
  • changing an item's behaviour or a player-head skin
  • adding a new custom fishing rod

Changes that only touch textures, models, menus, fonts or sounds go live when Bedrock players rejoin. /npb status shows whether a pack is waiting for a restart. Also remember that a brand-new installation needs one restart after the first start, so Geyser can load the NusaPack extension.

Geyser on a proxy

NusaPack does not support Geyser running on a Velocity or BungeeCord proxy yet. Install Geyser-Spigot on the Paper server itself and leave geyser_extension on auto, so NusaPack can manage its extension. The manual value only stops NusaPack from touching Geyser's extensions folder; it does not make a proxy setup supported.

If /npb check says the extension is missing, make sure Geyser-Spigot is installed on this server and that you restarted once after the first start.

Untested versions and unsupported servers

  • Content plugin versions other than the tested ones still convert, with a one-time "untested version" warning. /npb check shows which of your versions are tested.
  • ModelEngine must be R4. R3 has a different API and is not supported.
  • Folia is not supported yet.
  • On Minecraft versions other than 1.21.4, the furniture bridge turns itself off. Everything else keeps working.

Asking for help

When you contact support, include:

  • the output of /npb check, which shows the versions in use
  • the output of /npb report errors, if a conversion failed
  • what you changed, and what Bedrock players see

Never include your license key in messages, logs or screenshots.

Next steps

Nusa product documentation · NusaPackPaper 1.21.x · Java 21

Loading the index…