# Troubleshooting

Fixes for the problems people actually run into with Koja HUD, grouped by symptom.
Turn on `KOJA.Debug = true` while you investigate — the F8 console then shows what the HUD is doing.

:::accordion{title="Nothing appears at all"}
- **Start order.** `koja-lib` and `oxmysql` must be `ensure`d before `koja-hud`. Check the server console for an error from `koja-hud` on start.
- **Folder name.** The folder must be `koja-hud`. Resource names are the folder name.
- **No build.** `web/build/index.html` must exist. If you cloned the source instead of downloading a release, run the build — see [UI development](/free/hud/ui-development#building-the-ui).
- **Character not loaded.** The HUD waits for your framework's "player loaded" event (`esx:playerLoaded`, `QBCore:Client:OnPlayerLoaded`, `ox:playerLoaded`). A multicharacter resource that never fires it leaves the HUD hidden.
- **Hidden by the player.** **Settings → MAIN → HUD Settings → HUD Visibility** may be off. Resetting settings in the menu restores the defaults.
:::

:::accordion{title="An export does nothing"}
`exports['koja-hud']` must match the folder name exactly, and exports only exist on the **client**.
Calling one from a server script errors; use a client event instead — see [Exports & Events](/free/hud/exports-and-events#from-the-server).
:::

:::accordion{title="I changed js.json and nothing changed"}
`js.json` is compiled into the UI. Rebuild it with `pnpm build` in `web/` and restart the resource — see [Player settings](/free/hud/player-settings).

If you did rebuild: players keep their own choices. A new default only reaches players who never changed that option. Ask them to reset their settings in the menu to check.
:::

:::accordion{title="Hunger and thirst stay at 0"}
- **ESX:** `esx_status` (and something that uses it, such as `esx_basicneeds`) must be running.
- **QBCore / QBox:** values come from the player's `metadata.hunger` and `metadata.thirst`.
- **ox_core:** the HUD listens for the `ox:statusTick` event.

If your server uses another needs resource, the bars have no data source.
Point them at it by editing `KOJA.Client.StatusTick` in `client/main.lua`: it must call `KOJA.Client.RefreshStatus(hunger, thirst)` with two values from 0 to 100.
:::

:::accordion{title="The voice bar never moves"}
It reads the range from pma-voice's `pma-voice:setTalkingMode` event.
Without pma-voice, or with `KOJA.Microphone.Custom = true`, nothing updates it.
The "talking" highlight is separate and works with any voice system.
:::

:::accordion{title="Fuel always shows full, or always empty"}
The HUD reads fuel through koja-lib, which supports `ox_fuel`, `LegacyFuel` and the native fuel level.
Another fuel resource that stores fuel its own way needs support added to koja-lib.
:::

:::accordion{title="Nitro: “You are not owner of this vehicle”"}
- `KOJA.Nitro.Tables` does not match your database. On QBCore and QBox use `player_vehicles` and `citizenid`.
- The vehicle is not in the owned-vehicles table — a spawned or rented car never has nitro.
- The vehicle's plate in the world differs from the plate stored in the table.
:::

:::accordion{title="Nitro: SQL error on start"}
Your database is MySQL rather than MariaDB, which does not accept `ADD COLUMN IF NOT EXISTS`.
Add the column by hand once — see [Database](/free/hud/database).
:::

:::accordion{title="Nitro item is not used / nothing happens when I use it"}
The HUD does not register the item as usable. Register it in your framework and call `SetNitro` on the client — the full snippet is in [SetNitro](/free/hud/exports-and-events#setnitro).
:::

:::accordion{title="The car will not move after I get in"}
That is the engine feature: with `KOJA.Engine.StartEngineOnEntering = false`, a vehicle whose engine is off stays off until you press **B**.
Set `StartEngineOnEntering = true` if you prefer engines to start on entry.
:::

:::accordion{title="I cannot get out of the car"}
The seatbelt is on. Press **L** to unfasten it, then **F**.
:::

:::accordion{title="The minimap is round, misplaced or missing"}
- Round: `KOJA.MiniMap.Enabled` is `false`, or another resource replaces the radar textures after the HUD.
- Missing: check **Settings → MAIN → Minimap** (it may be set to **In Vehicle** or **Never**), and `KOJA.NeedItemForMinimap`.
- Misplaced on an ultrawide screen: drag it into place in **Settings → Edit layout**, or tune the offsets in [Configuration](/free/hud/configuration#fine-tuning-the-minimap).
:::

:::accordion{title="Two progress bars or two notification systems"}
Another resource draws its own. Hide the HUD's version with `KOJA.HideComponents` (for example `progressbar = true`), or route the HUD's messages elsewhere with `KOJA.Notify` — see [Configuration](/free/hud/configuration#forcing-components-off).
:::

:::accordion{title="Key binds conflict with other scripts"}
Players can move the HUD's keys in **Settings → BINDS** or in GTA's **Key Bindings → FiveM**. To change the defaults for everyone, edit the `Key` values in `config.lua` **and** `builtinBinds` / `activeBinds` in `js.json`, then rebuild the UI.
:::

## Still stuck?

Ask on [discord.gg/hexelstore](https://discord.gg/hexelstore) with your framework, the HUD version (`fxmanifest.lua` → `version`), and any errors from the server console and F8.