Troubleshooting
On this page4 sections
- First checks
- Startup and reload messages
- Common problems
- I do not see my own nametag
- The nametag is not shown for some players
- Bedrock players see vanilla nametags
- A badge shows as text like [VIP] or VIP
- Badge corners are not transparent
- A sprite shows as a purple and black square
- Vanilla nametags still show or are duplicated
- My template is not applied
- A placeholder shows as %...%
- A text effect is not animated
- Animations look choppy or a keyframe turns the wrong way
- Nametags flicker or vanish after /reload or a plugin manager
- Reading /nametag debug
First checks
- The console at startup. A working install logs
Enabled with N template(s), storage: YAML, hooks: PlaceholderAPI, LuckPerms. Configuration problems follow asFound N configuration problem(s); defaults were used for them:with the file and path of each one. /nametag reloadlists the same problems in chat (the first ten)./nametag info <player>shows the template a player really has, their lines and every customisation an admin gave them./nametag try <template>and/nametag self on(then F5) to look at a design yourself.
Startup and reload messages
| Message | Meaning and fix |
|---|---|
PacketEvents is required ... Disabling. | Install PacketEvents (opens in a new tab) 2.14+ in plugins/. |
PacketEvents X is older than 2.14.0; nametags may not work | Update PacketEvents. |
AdvancedNametags requires Minecraft 1.21.11 or newer | The server is older than 1.21.11; update it. |
AdvancedNametags needs Paper or a Paper fork | Spigot and CraftBukkit lack the APIs it uses; run Paper, Purpur or Folia. |
Could not connect to the database; falling back to YAML storage. | Check storage.sql (host, port, database, user, password) and that the database exists, then restart. Until then, changes are stored in data/players/. |
storage.type changed; restart the server to switch storage backends. | The storage only changes on a restart. |
Reload cancelled, nothing changed: a file has a YAML syntax error | The line and column follow. Usual causes: a tab instead of spaces, a missing quote, a : or # inside unquoted text. Quote every line that starts with <, %, { or contains : . |
no template without permission/groups exists; added a built-in 'default' | Add a template with permission: none (see templates). |
a template with this id already exists in another file; skipped | The same id is in nametags.yml and a file in templates/; rename one. |
unknown motion 'flaot' (float, breathe, ...) | A typo, or a motion not defined in animations.yml. The same for transitions and reactions. |
the badge font has no 'x' | Badge text supports letters, digits, space and + - ! ? . : / & * [ ] # $ ' _ =. |
badge images must be 8 px tall | Resize the PNG in badges/ to a height of exactly 8 pixels. |
only item and block rows can glow; ignored | glow on a text line; use a coloured shadow instead. |
'gold' is a standard MiniMessage tag; choose another name | A preset in animations.yml cannot be called like a MiniMessage tag. |
Invalid MiniMessage: ... (in '...') / Unknown animation 'x' | Logged once when a line is drawn; the line is shown without the broken part. |
Line longer than 256 characters was truncated | A placeholder returned a huge value; see performance.max-line-length. |
Common problems
I do not see my own nametag
Players see their own nametag in third person (F5) by default. If you don't, it was turned off:
/nametag self on. The default is self-view.default in config.yml (true in new installs).
The nametag is not shown for some players
visibility.max-distance(48), and betweenalways-visible-distance(24) and that, only nametags in front of the viewer (fov).- Invisible players and spectators have no nametag (
hide-invisible,hide-spectators). visibility.through-walls: hidehides players behind solid blocks;sneak.hidewhile sneaking.disabled-worlds, a template withworlds:,/nametag set <player> hidden true, another plugin using the API, or the viewer turned others off (/nametag others).- More than
performance.max-visible-per-viewer(60) players nearby: only the nearest are shown.
Bedrock players see vanilla nametags
That is the default: Bedrock (Geyser) cannot draw display entities, so with Floodgate installed
Bedrock viewers keep the vanilla nametag (compatibility.bedrock-viewers: vanilla). Without
Floodgate, Bedrock players cannot be detected and are treated like Java players.
A badge shows as text like [VIP] or VIP
That is its fallback, shown when the client is older than 1.21.9 (ViaVersion) or on Bedrock,
or when the badge's textures are not generated yet: run /nametag badges generate (the menu
/nametag badges shows which badges need it). A literal <badge:vip> means no badge has that id.
Badge corners are not transparent
Minecraft always draws a skin's face opaque; only resource-pack skins can be transparent. Use
corner: "#RRGGBB" to paint the four corner pixels. See
badges.
A sprite shows as a purple and black square
The texture path does not exist in the player's game version. Check the atlas and the path:
<sprite:items:item/diamond>, <sprite:gui:hud/heart/full>, <sprite:block/stone>.
Vanilla nametags still show or are duplicated
Check vanilla-nametag.hide: true. Another plugin may change nametag visibility in a way that is
not sent as team packets; with TAB nothing needs configuring.
My template is not applied
/nametag info <player> shows the applied template. Common causes: a higher-priority template also
matches (/nametag templates lists them by priority), the group name differs from your LuckPerms
group, the template has worlds:, the player picked another style (/nametag style auto), or an
admin forced one (/nametag unset <player> template). Operators do not get template permissions
automatically.
A placeholder shows as %...%
PlaceholderAPI or its expansion is missing: /papi ecloud download <expansion> and /papi reload.
A tag from a placeholder shown as text (<badge:vip>) means the placeholder is not
trusted.
A text effect is not animated
<rainbow> and <gradient> are MiniMessage's static tags: use <anim:rainbow>. Effects freeze
beyond performance.animation-distance and outside the view cone. /nametag set <player> animation
only affects bare <anim> tags.
Animations look choppy or a keyframe turns the wrong way
Movement is smooth unless it is far away (keyframes are spread out up to animation-distance) or
the bandwidth budget is hit in a crowd. Colour effects are frame by frame: lower
animations.text-effect-interval for more frames. Keep turns under 180° between two keyframes.
Nametags flicker or vanish after /reload or a plugin manager
Restart the server instead; Paper does not support reloading plugins, and packet plugins break first.
Reading /nametag debug
| Field | Meaning |
|---|---|
| Nametags / viewers | players with a nametag / connections being served |
| storage, hooks | the storage in use (YAML if the database failed) and the detected integrations |
| Render dispatch last / max µs | time of the last and the slowest render tick since the last /nametag debug (the max resets each time); per viewer avg is the work per viewer on network threads |
| spawns / destroys | nametags created and removed for viewers |
| metadata packets | text, style and pose updates sent |
| motion keyframes / text effect frames | movement and colour traffic |
| skipped renders | frames that were not needed (nothing changed) |
| held back by the budget | frames delayed by max-animation-bandwidth; a high, growing number means the budget is limiting a crowd |
The totals count since startup; run it twice a few seconds apart to see the rate.