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
/npb checkshows the versions in use and checks the usual reasons Bedrock players still see vanilla items, each with its fix./npb report errorslists every problem from the last conversion, with the reason.
/npb check looks for these common causes:
- Geyser is missing, or
enable-custom-contentisfalsein Geyser's config. force-resource-packsisfalsein Geyser's config, so players can refuse the pack.nusapack-geyser.jaris missing fromplugins/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
| Symptom | What to do |
|---|---|
| Bedrock players see nothing new | Read 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" warning | The 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 small | Set its size in glyphs.yml (copy the entry from glyphs-auto.yml), convert, then rejoin. |
| A custom menu is a plain chest on Bedrock | Run /npb gui scan, or open the menu and run /npb gui capture. Then convert and rejoin. |
| A chest menu looks shifted | Run /npb gui tune <id> offset_x <px> or offset_y <px>, then convert and rejoin. |
| Furniture bridge disabled | Read the log line. Furniture display needs Minecraft 1.21.4. |
| "NusaPack Bridge is locked", or the plugin is disabled at startup | Licensed builds only. Read the license lines in the console, fix the key in nusa-license.properties, and restart. |
/npb convert stops before converting | The 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 checkshows 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
- Everyday use: the normal convert, rejoin and restart routine.
- Supported content: what converts and the current limits.
- Commands: all options of
/npb gui,/npb reportand/npb pack.