> ## Documentation Index
> Fetch the complete documentation index at: https://docs.revoscripts.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Solutions to common Revo HUD issues, and how to use debug mode.

## Common Problems

> **The HUD never appears and the console says it was renamed**
>
> Rename the folder back to `revo_hud` and use `ensure revo_hud` in `server.cfg`. The resource does not start under another name.

> **The HUD never appears**
>
> The HUD waits for your framework to load a character.
>
> * On a custom framework, call `exports['revo_hud']:setCharacterLoaded(true)` when the character loads, or set `Config.Visibility.waitForCharacter = false`.
> * A third-person camera script that keeps a camera on all the time also needs `Config.Visibility.ignoreScriptCameras = true`.
> * Turn on `Config.Debug` and check the F8 console. It says why the HUD is hidden.

> **My logo doesn't show**
>
> The file has to be in `revo_hud/html/dist/` with the exact name in `logoPath` (capital letters count), or `logoPath` has to be a full `https://` link. If it is missing, the HUD shows `logoText` instead.

> **Notifications show twice**
>
> Another notify script is installed alongside the HUD's bridge for it. See [Notifications](/products/hud/configuration#notifications). QBCore and Qbox draw `QBCore:Notify` themselves, which is why `overrideQBCore` is off by default.

> **The map style didn't change**
>
> * Check the files are in `maps/postal/` (or `maps/satellite/`).
> * Check `mapStyle` is spelled exactly `'postal'`, `'satellite'` or `'stock'`, and `zoomLevel` is `1100` for postal or satellite.
> * Restart `revo_hud`. The server console says which style is active.
> * Players may need to clear their FiveM cache once.

> **Hunger and thirst are missing**
>
> Nothing on the server supplies them (no `esx_status` and no framework metadata). They hide themselves rather than sit at 100. Feed them with the `setStatus` export, or set `Config.HideUnfedStatuses = false`.

> **Nobody can fit nitrous**
>
> The nitrous items are missing from your inventory. See [Nitrous](/products/hud/usage#add-the-items), or set `Config.Nitro.fitting = 'all'` to give every car a kit. With `Config.Debug` on, the server console says whether the items were registered.

> **The media player does nothing**
>
> The media player needs **OneSync**. Check it is enabled on your server.

> **/hud does nothing for players**
>
> Customization is locked: `Config.Customization.allowPlayersToEditSettings` is `false`. Staff with the `revo_hud.admin` ACE can still open it when `adminsBypassLocks` is on.

> **Staff cannot edit while players are locked out**
>
> Make sure the ACE is in your `server.cfg` and the server was restarted:
>
> ```bash theme={null}
> add_ace group.admin revo_hud.admin allow
> ```
>
> Also make sure your admins are in `group.admin` (or change the line to match your admin group), and that `Config.Customization.adminsBypassLocks` is `true`.

> **A key hint shows a different key than I set in the config**
>
> The hint panel shows the key each player **bound**. FiveM keeps a player's key in their own profile after they first see a bind, so a change in `config.lua` only reaches players who have never seen it. Players can change it in **Settings > Key Bindings > FiveM**.

> **A player's HUD is a mess**
>
> **Reset Defaults** at the bottom of `/hud` puts back your server's look. Or set `Config.Customization.forcePreset = true` to re-apply your default preset on every join.

> **The HUD shows a speed or limit in the wrong unit**
>
> `Config.DefaultSpeedUnit` only sets the unit for new players, and each player can switch in the menu. Speeds in `config.lua` are always km/h.

## Debug Mode

Set `Config.Debug = true` in `config.lua` and restart the resource. The HUD then prints what it finds and does to the F8 console (and the server's side to the server console): which framework and fuel script it uses, why the HUD is hidden, crashes and nitrous.

It also adds the `/revohud_debug <check>` command:

| Check | What it shows |
| - | - |
| `audience` | Your job, vehicle class and which features you get |
| `money` | What the HUD reads as cash and bank |
| `vehicle` | Doors, windows and indicators of the car you are in |
| `gears` | The gearbox's numbers for the car you are in |
| `lights` | What the headlight natives report |
| `crosshair` | What decides the crosshair, for ten seconds |
| `nitro` | The nitrous state of the car you are in |

> [!WARNING]
>
> Leave debug mode off on a live server.

## Still Having Issues?

See the general [Troubleshooting](/general/troubleshooting) page, or join our [Discord](https://discord.gg/EbHGgQaYKe) for support. When you ask for help, include your server framework, the resources you use for fuel, voice and inventory, and any red errors from the F8 or server console.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.