Troubleshooting

Common problems with oxide-hud and how to fix them. Work down each list from the top — the first fix is the most likely one.

Where to Find Messages

Oxide HUD has no debug mode and prints only a few messages of its own (an o-link that is too old, an accent, a default layout or a server logo it cannot use, and a panel from another resource it could not register). Two places tell you what is wrong:

• The server console: the black window (or the txAdmin Live Console) where your server prints Started resource ... lines.
• The client console: press F8 in game. Errors from scripts show here in red, starting with SCRIPT ERROR.

o-link prints a line whenever it skips a resource because that resource was not running yet, for example:

[o-link] Fuel adapter "ox_fuel" skipped: resource "ox_fuel" is stopped (not started)

These lines appear while Config.Debug = true in o-link/config.lua (the default). They usually mean a start-order problem.

The HUD Never Shows

Symptoms:

• Nothing appears after you pick a character.
• /hud does nothing.

Solutions:

1. Pick a character first. The HUD appears once your character has loaded. It never shows on the character select screen, and /hud does nothing until then.

2. Check the download is complete. This file must exist:

   resources/oxide-hud/web/dist/index.html

   If it is missing, download oxide-hud again from your assets on the Cfx.re Portal, replace the folder, and restart your server.

3. Check the server's license key. Oxide HUD is protected (escrowed), so it only starts on a server whose license key (sv_licenseKey in server.cfg) belongs to the same Cfx.re account that claimed Oxide HUD. If the server console shows an error about oxide-hud when it starts, claim Oxide HUD with the account that owns the key, or use a key from the account that claimed it.

4. Check that o-link is installed. If the server console shows this when oxide-hud starts, the server cannot find o-link:

   Could not find dependency o-link for resource oxide-hud.

   Make sure the o-link folder is inside your resources folder and is named exactly o-link, not o-link-main.

5. Update o-link. If the server console or the F8 console shows this line, your o-link is too old and the HUD stays off on purpose:

   [oxide-hud] Oxide HUD needs o-link 1.12.0 or newer (found 1.11.0). The HUD stays off until o-link is updated.

   Download the latest o-link, replace the folder (keep your config.lua), and restart your server.

6. Check that nothing is hiding it. The HUD hides on purpose while the pause menu is open, while you are dead or downed, while Oxide Phone is open, while another script's window has control of the mouse or keyboard, and while another resource shows a camera view or a cutscene. If a mouse cursor is stuck on screen, or your keys stop working in game, another script left its window open; close it, or restart that script. If the HUD stays hidden after a camera view or cutscene has ended, restart the resource that showed it. See When the HUD Hides.

7. Check the folder. It must be named exactly oxide-hud, with fxmanifest.lua directly inside it.

Two HUDs on Screen

Symptoms:

• Health, hunger or a speedometer appear twice, in different styles.
• Pieces of HUD overlap things you did not put there.

Solutions:

1. Stop your framework's own HUD. qb-hud (QBCore), qbx_hud (Qbox) or esx_hud (ESX) must not run alongside Oxide HUD. Remove its ensure line.

2. Check for a folder line. A line such as ensure [qb] starts every resource in that folder, including the framework's HUD. Move that HUD's folder (for example qb-hud) out of your resources folder, so the folder line no longer starts it. See Removing Your Framework's HUD.

3. Check for a third-party HUD. Any other HUD resource draws its own HUD too. Remove it the same way.

4. Restart your server.

The HUD Shows Before Picking a Character, or the Name, Cash and Bank Are Empty

Symptoms:

• The HUD is already on screen at character select or right after joining.
• The character name is blank, and cash and bank show 0, even though the character has money.

Solutions:

1. Fix the start order. o-link started before your framework, so it could not find it and the HUD thinks there is no framework. Open your server.cfg and make sure your framework comes first, then ensure o-link, then ensure oxide-hud. Also make sure ensure oxide-hud is not above your framework: starting oxide-hud starts o-link straight away. See Start Order. The console usually shows a line like:

   [o-link] Framework adapter "qb-core" skipped: resource "qb-core" is stopped (not started)

2. Restart the whole server after changing the order.

Notes:

• On a server with no framework at all, this is expected: there is no character, so the name stays empty and cash and bank show 0.

Status Bars Are Missing

Symptoms:

• Health, hunger, thirst or stress never appear.

Solutions:

1. This is usually auto-hide. Status blocks only show while they have something to report. Health hides at full health, armour and stress at 0, and hunger and thirst while they are 80 or more. Take some damage or sprint for a few seconds to check: health or stamina should appear. To keep a value on screen all the time for everyone, see Auto-Hide. A player can also change it for one block: select it in /hud and set Hide to Never under Rules.

2. Your framework may not track it. Stock ESX has no stress (unless a script registers an esx_status called stress), and a server without a needs system has no hunger or thirst. A need that is not tracked reads as full, so its block stays hidden unless its Hide rule is set to Never.

3. Check the block is in the HUD. Type /hud. In the editor every block shows, even full ones. If one is not there, add it from the Add tab: pick the status, then a style. Check the Layers tab too: a block with its eye closed is hidden.

The Seatbelt Light Is Always On

Symptoms:

• The seatbelt warning glows all the time, even with the belt fastened.

Solutions:

1. Run a seatbelt resource Oxide HUD can read. That is qbx_seatbelt or qb-smallresources. Without one, nothing tells the HUD when the belt is on, so the light shows it as off. Restart the server after installing one.

2. Pick the right one. If more than one is installed, set Seatbelt in o-link's config.lua. See Choosing Seatbelt, Voice and Fuel Resources.

3. No seatbelts on your server? Leave seatbelt lamps out of the HUD. The Ghost speedometer (a SEATBELT chip), the Instrument speedometer and, in the classic set, Blade, Carbon, Zenith and Redline have one built in; the default Sweep speedometer does not. To remove it from a speedometer, double click the lamp in /hud and press Delete. To give every player a HUD without one, see Default Layout.

The Fuel Gauge Does Not Match Your Fuel Script

Symptoms:

• The fuel gauge shows a different level than your fuel script.
• The gauge never goes down, or jumps around.

Solutions:

1. Start your fuel script before o-link. o-link only uses a fuel resource that is already running when o-link starts. Otherwise it falls back to GTA's own fuel level. Move the fuel script's ensure line above ensure o-link, and restart the server. A line like [o-link] Fuel adapter "..." skipped in the console means this is the problem.

2. Check your fuel script is supported. The list is in Optional Resources. With any other fuel script, the gauge shows GTA's own fuel level.

3. Two fuel resources? Set Fuel in o-link's config.lua. See Choosing Seatbelt, Voice and Fuel Resources.

Notes:

• The fuel level is read once a second (Config.Intervals.fuel), so a short delay is normal.

The Voice Indicator Is Missing or Never Changes

Symptoms:

• The voice indicator does not appear at all.
• The range bars never change when you switch range.

Solutions:

1. Voice chat must be connected. Voice blocks only appear while voice chat is connected. A player who turned voice chat off in GTA's settings, or a server with voice chat disabled, sees no voice indicator.

2. Run pma-voice or SaltyChat for range steps. FiveM's built-in voice chat has only one range, so the bars never change without one of them.

3. Both installed? Set Voice in o-link's config.lua to the one you use. See Choosing Seatbelt, Voice and Fuel Resources.

The Radio Is Empty or Missing

Symptoms:

• The radio is not on screen.
• It never shows a channel.

Solutions:

1. Join a radio channel. The radio only appears while you are on a radio channel, or transmitting. Off the radio, it disappears. In the editor it shows Off so you can place it; pick On the radio in the editor's sample data menu to see it with a channel.

2. You need pma-voice or SaltyChat. FiveM's built-in voice chat has no radio, so without one of them the radio never appears.

3. Your radio item must use that voice resource. The radio shows the channel your voice resource reports. A radio script that does not join channels through pma-voice or SaltyChat does not show up here.

The Minimap Only Shows in a Vehicle

Symptoms:

• The minimap disappears when you get out of a vehicle.

Solutions:

1. This is the default. Hide on foot is on for every player at first. To change it, type /hud, click the minimap's box (or Minimap in the Layers tab) and switch off Hide on foot in the inspector. Each player chooses this for themselves.

2. Minimap in the wrong place? In the editor, drag the minimap's box, or select it and click Put back in the corner. Reset also moves it back, but it puts that mode's HUD back to the default too (see Reset).

Server Logo Does Not Show

Symptoms:

• No logo in the top-right corner.

Solutions:

1. Turn it on. The logo is off until you set it up. In config.lua, Config.ServerLogo.enabled must be true and Config.ServerLogo.image must not be empty. Then type restart oxide-hud in the server console.

2. Check F8. Press F8 in game. A line starting [oxide-hud] The server logo could not be loaded from shows the exact address the HUD tried, which tells you which of the checks below applies. No such line while the logo is on means the image loaded; look at the top-right corner with the pause menu closed.

3. Using a web address?

   • It must start with https:// and point straight at the image (it usually ends in .png or .jpg), not at a web page that shows the image.
   • Use a link that does not expire, such as an image on your own website. Images hosted on imgur never load in FiveM, and Discord attachment links stop working after about a day.

4. Using a file inside oxide-hud?

   • The file must sit in the oxide-hud folder, next to config.lua.
   • Its name must be listed in the files { block of oxide-hud/fxmanifest.lua. See Server Logo.
   • The name in config.lua must match the file exactly, including capital letters and the extension.
   • Restart the whole server, not just oxide-hud, after changing fxmanifest.lua.

5. Did you update oxide-hud? An update replaces fxmanifest.lua, which removes your logo line. Add it again and copy the image back.

Notes:

• The logo hides with the rest of the HUD, for example in the pause menu.

Text Is Still in English After Translating

Symptoms:

• The editor and HUD labels are in English, or partly in English, after you added a translation.

Solutions:

1. Check the language line in server.cfg. It must use setr, not set, and match your file's name:

   setr ox:locale de

   for locales/de.json. set keeps the setting on the server, and the HUD reads it on each player's side.

2. Check the file is valid. One missing comma or quote breaks the whole file, and the HUD falls back to English. Paste the file into any online JSON checker to find the mistake.

3. Check the file's place and name. It must be in oxide-hud/locales/, named with the same code you set, ending in .json.

4. Restart the whole server after adding the file or changing the language.

Notes:

• Lines missing from your file show in English. Compare your file with en.json after each update.
• Street and area names come from GTA and follow each player's game language, not your translation.

Other Resources' Panels Overlap the HUD

Symptoms:

• A notification area, progress bar or job panel from another resource covers part of the HUD, or another panel.

Solutions:

1. Check the resource supports it. Only resources that place their panels through o-link's HUD feature are moved clear of Oxide HUD. Panels from other resources draw where they always do. Move your own blocks out of their way in /hud.

2. Reserve space for things Oxide HUD cannot see. A chat box from a chat resource that does not support Oxide HUD, or a third-party display, is invisible to Oxide HUD. Add its area to Config.ReservedAreas so panels are placed clear of it. See Reserved Areas.

3. Drag the panel. In /hud, other resources' panels show as dashed boxes (purple, or your server's accent colour). Drag one somewhere else. Its new spot is saved for that mode (on foot or in vehicle).

4. A full side of the screen. With many resources on one side (notifications, dispatch alerts, a phone, a job card) and a vehicle cluster below them, there may be no free room left. The last panels to be placed then sit over other panels, covering as little as possible and covering alerts and notifications last, rather than over the HUD. Switch off panels a player does not use (Show in game), or drag some to the other side.

5. Keep the folder name. o-link looks for a resource called exactly oxide-hud. Under any other name, other resources cannot find the HUD and place their panels as if there were none.

Notes:

• Short-lived panels, such as a prompt or a progress bar, keep clear of the HUD but may sit on top of other panels. That is by design.
• A panel a player has moved stays where they put it. Reserved areas do not push it.

The Layout Looks Wrong After Changing Resolution

Symptoms:

• After switching resolution, monitor or window size, pieces of the HUD are further apart, closer together, or pushed against an edge.

Solutions:

1. Drag what you want elsewhere. Every block and group is pinned to the edge or corner of the screen it was dropped in and sized to the screen height, so a layout keeps its look at the same shape of screen. On a wider or narrower screen, pieces at the edges stay at the edges, so the gaps between them change. Open /hud and move what you need: each piece is pinned again to the part of the screen you drop it in.

2. Going back to the old screen? A piece that did not fit on the new screen was only pulled onto it for display. Its saved spot is kept, so it returns to its place on the original screen.

3. Save a layout for each screen. Save one for each screen you play on (Share > My layouts > Save) and use the matching one.

4. Start over. Reset this layout (in the editor's ... menu) puts the mode you are editing back to the default and puts the minimap and other resources' panels back. Do it once for On Foot and once for In Vehicle to start both from the default. See Reset.

The Default Layout Is Not Used

Symptoms:

• You set Config.DefaultLayout, but new players still get Oxide HUD's own layout.
• The F8 console shows a line starting [oxide-hud] Config.DefaultLayout cannot be used:.

Solutions:

1. Read the reason on that line. It says why the code was refused:

   Reason	Fix
   it is not an Oxide HUD share code	Copy the code again from Share > Share code. It starts with OXHUD1.
   it was made by a newer version of Oxide HUD	Update oxide-hud on this server, or make the code again here
   it is longer than 20,000 characters	Use fewer blocks, then copy it again
   it is damaged or cut short	Copy the whole code again. Some editors cut long lines; paste it into config.lua with a plain text editor
   it contains a web address or an image path	In /hud, remove any web address or file name (such as https://discord.gg/... or logo.png) typed into a text block, label or name, then copy the code again
   it has more than 100 blocks in one mode	Remove some blocks, then copy it again
   its groups are nested too deeply	Ungroup some groups, then copy it again
   this game client cannot unpack it	That player's game cannot unpack compressed codes. Ask them to update FiveM
   it has nothing this HUD can show	The code holds nothing to draw. Make it again with Whole HUD chosen

2. Restart oxide-hud after changing config.lua.

3. Players who changed their HUD keep it. The default is used by every player who has never changed their HUD in the editor, and by Reset. A player who changed theirs can switch with Reset or Share > My layouts > Default. To give everyone your layout, also set Config.LockEditing = true (see Locking the Editor).

4. Your own colours travel with the code. A whole-HUD code carries the Theme tab colours of the player who copied it, and every player on your default gets them. Put your Theme tab back to the server's accent before copying the code.

A Share Code Will Not Load

Symptoms:

• Check code in Share > Use a code shows a red message instead of a preview.

Solutions:

1. Copy the whole code. It is one long line starting with OXHUD1.. This code is damaged or cut short means part of it is missing; chat programs sometimes cut or change long messages, so share it as a file or in a code block.

2. A newer version made it. This code was made by a newer version of Oxide HUD means the server needs updating.

3. Too large. Codes stop at 20,000 characters and 100 blocks in one mode. Share a group instead of the whole HUD.

4. Web addresses are refused. A code that contains a web address or an image path anywhere is refused, so a code cannot make other players' games load anything from the internet.

Notes:

• ... blocks this HUD does not know are left out is not an error: the code was made with something this version cannot draw, and the rest is kept.

/hud Does Nothing

Symptoms:

• Typing /hud does not open the editor.

Solutions:

1. Wait for your character to load. The editor only opens once the HUD is on screen. If the HUD never shows, see The HUD Never Shows.

2. Check the command name. The command is set by Config.EditCommand in config.lua. If someone changed it, use the new name.

3. Another script may use /hud too. Only one of them can own the command. Set Config.EditCommand to something else, for example 'hudedit', and restart oxide-hud.

/hud Says Editing Is Turned Off

Symptoms:

• Typing /hud shows Editing the HUD is turned off on this server.

Solutions:

1. This is on purpose. Config.LockEditing is true in config.lua, so every player sees the server's default layout and the editor does not open. Set it to false and restart oxide-hud to let players edit again; their own HUDs come back. See Locking the Editor.

Getting Help

If none of the above fixes your problem:

1. Press F8 in game and copy every red line that mentions oxide-hud or o-link.
2. Note the order of your framework, fuel, voice, o-link and oxide-hud lines in server.cfg.
3. Note your oxide-hud and o-link versions (the version line in each fxmanifest.lua).
4. Type oxide:diag in your server console. o-link writes a support file into o-link/diag/ that lists which resource it uses for each feature. Attach it.
5. Open a support ticket on the Oxide Studios Discord with all of the above.

Next Steps