FAQ and troubleshooting
Start with /fb debug when you need help. It writes a report with the plugin version, loaded boards, configuration and recent errors to Ubuntu Paste. Share the link together with the exact steps that reproduce the problem.
Installation and startup
The plugin does not start or the folder is not created
FeatherBoard needs ProtocolLib and PlaceholderAPI. Confirm that both jars are in plugins/, are enabled, and are built for your server version. Check the first lines of the server log for the missing dependency.
Which server versions are supported?
FeatherBoard 7 targets Spigot 26.3 and Java 25. Paper usually works but is not the tested target; other server implementations are not supported. If you run an older server line, use the FeatherBoard release built for that line.
The plugin loads but there is no scoreboard
Check in this order:
- Does the player have
featherboard.group.<board>? - Is the board enabled and assigned? See assigning scoreboards.
- Is the world in
disabled-worlds? - Is
tweaks.default-hiddenenabled? Players then need/fb on. - Run
/fb show <board>to bypass assignment and see whether the board itself works. - Read the console after
/fb reload <board>for YAML errors.
The scoreboard disappears after a restart
FeatherBoard stores per-player toggle and override state in its database. If a player ran /fb off, the board stays hidden after a restart. Run /fb on for that player. If the board disappears for everyone, check the YAML and the assignment method.
Display and YAML
My scoreboard shows multiple lines from other players, or ghost lines
This usually points at a client or packet conflict, or at stale scoreboard data. Try:
/fb debugand check for conflicting plugins.- Delete
scoreboard.datin the world'sdatafolder while the server is stopped. - Make sure ProtocolLib is up to date.
- Remove other scoreboard or tab plugins one at a time.
The scoreboard width changes while text scrolls
The board width is the longest line. Give the header or footer a line at least as wide as the scroll, or reduce <scroll width="...">. Images can also affect the width.
There are empty lines I did not configure
Use frames: [] for intentional spacers. If the empty lines appear after an update, stop the server and delete scoreboard.dat from the world's data folder, then restart.
My config keeps resetting or a board fails to load
This is almost always a YAML syntax error. Check indentation (spaces, not tabs), quote values containing & or %, and validate the file with an editor or yamllint.
Do not change the config: number in config.yml. If a setting is missing after an update, the plugin adds it on the next start.
The first line of my board is not the title
A separate title: section is preferred. If you use title:, the first entry under lines: is not the title. If you omit title:, the first line under lines: becomes the title.
Can I remove the red numbers?
Yes, on 1.20.3+ clients. Set tweaks.hide-score: true in config.yml (the default). This applies to every board. If you want numbers on one board, set it to false and hide them with the |hide| / |show| metadata where needed.
Placeholders
Placeholders stay visible as %name%
- Install the expansion that provides the placeholder:
/papi ecloud download <expansion>then/papi reload. - Check the expansion identifier in the PlaceholderAPI list.
- If
placeholder.auto-downloadis disabled, install the expansion manually. - Run
/fb parse <line>to test the line outside a board.
FeatherBoard 7 uses %placeholder%. The old {placeholder} syntax is not resolved.
Placeholders do not update
- Check the line's
interval; it controls how often the frame is rebuilt. - Some expansions cache values in MySQL or in memory. Wait for their cache to expire.
- Wrap slow values in
<repeat times="...">to avoid rebuilding them every tick. - Enable
tweaks.detect-animation-lagto see which placeholder is slow.
Can I use placeholders in settings?
Yes. Settings are substituted first and the result is parsed as a normal line, so a setting can contain a PlaceholderAPI placeholder.
The placeholder works in chat but not on the board
Check whether the placeholder is inside an effect that needs the raw text. Most effects resolve placeholders normally; placeholder and script handle them differently. Test the frame with /fb parse and check the console for expansion errors.
Images, fonts and resource packs
Images show as empty gaps
The client has not loaded the resource pack. Check:
resource-pack.enabled: true.- The pack is reachable at the configured URL.
- The
sha1matches the generated ZIP for manual hosting. - The player accepted the pack prompt.
Boards with images can define a fallback board for players who reject the pack:
settings:
fallback: "default"The resource pack prompt does not appear
The player may already have the pack cached, or the URL is unreachable. Delete the server's cached pack reference in the database, or join with a clean client. Check the console for upload errors from the local/SFTP/FTP destination.
Can I use GIF or SVG icons?
No. Images must be PNG or JPG. Animated icons can be made by switching between several PNGs in multiple frames.
Custom fonts do not render
Confirm the font is a .ttf, the identifier matches the one in |font:featherboard:<id>|, and the resource pack was accepted. Use |font:minecraft:default| to verify the rest of the line.
Performance
The server uses too much CPU
- Look for lines with a very low
intervaland expensive placeholders. - Replace repeated slow placeholders with
<repeat times="...">. - Check for conflicting scoreboard plugins.
- Run
/scoreboard objectives listand/scoreboard teams listto inspect conflicts. - Avoid
speed-multipliervalues above1.0unless you have tested them.
TPS is fine but players see lag
This can be network latency. Lower the refresh rate of animated lines, reduce the number of frames, and avoid very large resource packs. The board itself sends small packets; a high animation rate on many players adds up.
Many players quit and join
keep-scoreboard-quit: true can reduce work on hubs, but it can leave stale client state. Test it before enabling it on a production server.
Conflicts
Another plugin resets or hides my board
A plugin that creates its own scoreboard can take over the sidebar. FeatherBoard cannot prevent this for all plugins. Options:
- Disable the scoreboard feature of the other plugin.
- Use
prevent-override: truein the board settings. - Check
/scoreboard objectives listand/scoreboard teams listfor conflicting objectives.
mcMMO or another plugin shows errors about scoreboards
Disable that plugin's own scoreboard integration. FeatherBoard manages the sidebar; two plugins writing to it at the same time will conflict.
Can FeatherBoard work alongside another scoreboard plugin?
FeatherBoard is designed to own the scoreboard. Use one scoreboard plugin at a time. Some plugins can be configured to leave the sidebar alone; do that rather than running both.
Updates and support
An update broke my placeholders or board
Read the release notes and check the migration notes. Keep a backup of plugins/FeatherBoard/ before updating. If a key was renamed, the old key may still be read for compatibility, but the new name is recommended.
How do I get support?
- Reproduce the problem.
- Run
/fb debug. - Collect the server log around the error.
- Share the debug link, the board file and the steps to reproduce.
Do not paste your database password; /fb debug redacts it automatically, but screenshots of config.yml may not.
Useful links:
