• Start order. koja-lib and oxmysql must be ensured 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.
• 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.

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.

js.json is compiled into the UI. Rebuild it with pnpm build in web/ and restart the resource — see 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.

• 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.

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.

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.

• 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.

Your database is MySQL rather than MariaDB, which does not accept ADD COLUMN IF NOT EXISTS. Add the column by hand once — see Database.

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.

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.

The seatbelt is on. Press L to unfasten it, then F.

• 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.

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.

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.