Resource

Troubleshooting

Potential issues and how to fix them.

Plugin won't enable

Check your console for a message about a missing dependency. PacketEvents is a required dependency — if it isn't installed and enabled, CustomPlayerNametags won't start. The plugin also needs Paper 1.20 or newer; Spigot and Bukkit are not supported.

Placeholders show up as literal text

If placeholders appear unparsed above a player's head instead of resolving, PlaceholderAPI either isn't installed, isn't enabled, or doesn't have the specific expansion registered (e.g. the LuckPerms expansion for %luckperms_prefix%). Make sure PlaceholderAPI is installed and that there are no errors in the console. Next check your placeholder with /papi parse <username> <placeholder> in-game to confirm PlaceholderAPI itself can resolve it.

The global or group format isn't being used

• Global and group formats only work when PlaceholderAPI is installed. Without it, every nametag falls back to the player's username unless they have an individual format.
• Group formats also need LuckPerms. If a player is in several groups, the highest-weighted group that has a format is used.
• An individual format takes priority over both. Check with /nametags format player view <player>, and clear it with /nametags format player disable <player>.
• If separate Bedrock formats are enabled, Bedrock players use their own Bedrock format. See Bedrock formats.

Nametags are cut off with "..."

Each line is limited by nametag-line-max-characters (24 by default), measured after placeholders are resolved, and it applies to every nametag — including global and group formats. Raise the value, set nametag-truncate-indicator to false to drop the ..., or give specific players a higher limit with permissions.

A format keeps reverting to the plain username

A {widget} in the global or Bedrock global format probably has invalid syntax (for example, a missing {/widget}). Check the console for a warning, and run /nametags reload, which reports which format fell back. See Widgets.

Cross-world teleportation not working

The tag is a passenger entity, and cross-world/dimension teleport commands can fail while it's still attached. This is exactly what nametag-dismount-mode exists to solve — see the full explanation on the Configuration page. If you use Multiverse-Portals, also check the passenger-mode notice described there.

Nametags appear too high or too low

Adjust global-nametag-height-adjust until the heights are in the desired position.

How to fine-tune nametag height

Java and Bedrock nametag heights don't match

Adjust bedrock-height-adjust until the heights match.

How to fine-tune nametag height

Nametags go too low when a Bedrock player views someone crouching

Adjust bedrock-sneak-height-adjust until the height looks correct.

How to fine-tune nametag height

Lines of a multi-line nametag are too far apart or too close on Bedrock

Adjust bedrock-per-line-height-adjust. See Bedrock & Cross-Play.

Nametag not visible

• Confirm PacketEvents is actually enabled (not just installed) — check its own console output on startup.
• The viewer may have hidden nametags with the Toggle option in the /nametag menu.
• Try /nametags reload, then have the player rejoin.

My changes to messages.yml or gui.yml disappeared

Both files are reset to their defaults every time the server starts and aren't meant to be edited. The messages sent when a player's format changes can be customized in config.yml instead — see Configuration.

---