Troubleshooting

🌎 Choose language: EN — English · RU — Русский

Troubleshooting

Reading a configuration error

The engine checks the whole configuration before compiling any of it, and reports everything it found at once rather than one problem per restart. Each line names the file and the exact element:

layouts/main -> images -> 1: refers to "barr", which no file in images/ defines. Did you mean "bar"?

Read it as a path: the file layouts/main.yml, the images section, entry 1. Typos get a suggestion; the engine compares against what you actually defined.

A failed compile does not take the plugin down. /hudengine reload still works, so you can fix the file and reload rather than restart.

No HUD at all

1. Did the player get the pack? With delivery: none nothing is sent — see Resource pack.
2. Did they accept it? A declined pack means no HUD and no error.
3. Are they on Bedrock? Geyser clients cannot render this and are skipped by default (huds.disable-for-bedrock).
4. Did the client log a shader error? The pack replaces a core shader; if it fails to compile the client silently drops it and the HUD vanishes. Check the client log, not the server one.

The HUD is one row too low

Another plugin's boss bar is above ours. See Boss bars.

Another plugin's boss bar lost its bar

It uses the same colour we blank. Change pack.boss-bar-color. See Boss bars.

Text looks like smudges

Too small. Height is the font's scale times the element's scale, and under five pixels text stops being readable. The engine warns about this:

compiles to 2 pixels tall (font scale 8.0 times 0.3), which is too small to read

Characters are missing

The compile report lists what no font could draw:

characters no font could draw: ЀЍѐѝ

Either the script is not in include, or the font file genuinely lacks those glyphs. See Fonts.

Placeholders show as literal text

[papi:something] needs PlaceholderAPI installed and the relevant expansion downloaded. Built-in values like [health] need nothing — if those are also literal, the name is wrong; the full list is on How a HUD is built.

The player's head is wrong or missing

On an offline-mode server there is no skin to fetch, so a built-in face is drawn. Installing SkinRestorer or similar makes it work normally.

Changes did not appear

Text and positions update on /hudengine reload. New images, fonts and moved elements need the player to rejoin, because that is when a client reads a new pack.

Where to report

Issues. Include the server version, the plugin version, and the compile report from the console — it says more than a screenshot.