Troubleshooting

The HUD doesn't show up

The HUD waits until Bridge.IsLoaded() returns true. On Qbox and QBCore that is LocalPlayer.state.isLoggedIn, on ESX ESX.IsPlayerLoaded(), and on standalone the first spawn. If your server uses a different character system, replace Bridge.IsLoaded and Bridge.OnLoaded in custom/client/.

Also check that ensure saf-hud comes after your framework in server.cfg.

The minimap is grey or blank

Run /fixmap. It reloads the minimap without a reconnect. Some loading screens and character menus hide the radar while the HUD starts, which leaves it grey.

"You can't change that." when running /soe or /aop

The player doesn't have hud.manage. Check the add_ace line in server.cfg and that the player is in that group. Run test_ace player.<id> hud.manage in the server console to see what FiveM decides.

The postal cell is missing and /p does nothing

There is no postals.json in the saf-hud folder, or it is empty. Copy the one from your postal map. Each entry needs code, x and y.

The fuel indicator is always full

Your fuel script doesn't publish Entity(veh).state.fuel and isn't one of the scripts SAF HUD checks. Override Bridge.GetFuel with your fuel script's export, as in Custom servers.

The seatbelt indicator never lights

The HUD reads LocalPlayer.state.seatbelt or LocalPlayer.state.harness. If your seatbelt script uses something else, override Bridge.HasSeatbelt.

SOE and AOP reset after a restart

Config.SOE.onStart or Config.AOP.onStart is set to 'default'. Set them to 'last' to keep the values.

I changed an area id and the level is gone

The area id is the saved key. A new id starts at its default level. Change short and name instead when you only want a new label.