Resource

Troubleshooting

Common 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.

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.

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.

Tag height looks slightly off for Bedrock players

Confirm Floodgate is installed and enabled — that's how the plugin tells Bedrock viewers apart from Java ones. See Bedrock & Cross-Play.

Nametag not visible

• Confirm PacketEvents is actually enabled (not just installed) — check its own console output on startup.
• Try /nametags reload, then have the player rejoin.

---