> For the complete documentation index, see [llms.txt](https://devmosaic.gitbook.io/devmosaic/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://devmosaic.gitbook.io/devmosaic/resources/devmosaic-dm-hud/troubleshooting.md).

# Troubleshooting

Find your symptom, get the one-line fix.

{% hint style="success" %}
**Start here.** Type `restart dm-hud` in the server console and read the line it prints:

```
[dm-hud] v1.0.0 ready — framework: qbx
```

If your framework is named there, the install is fine and your problem is config, not setup.
{% endhint %}

## Nothing shows at all

<table><thead><tr><th width="240">Check</th><th>Fix</th></tr></thead><tbody><tr><td>Is ox_lib started first?</td><td>Move <code>ensure ox_lib</code> above <code>ensure dm-hud</code> in <code>server.cfg</code></td></tr><tr><td>Any red errors in F8?</td><td>Read the first one. The rest are usually knock-on</td></tr><tr><td>Did someone type <code>/dashhud</code>?</td><td>That toggles the whole HUD. Type it again</td></tr><tr><td>Is opacity at 0?</td><td><code>F7</code> → General → HUD opacity</td></tr></tbody></table>

## Two minimaps, or two sets of bars

Your old HUD is still running.

```cfg
# ensure qbx_hud
# ensure qb-hud
```

{% hint style="warning" %}
This is the single most common installation problem. Comment out the old HUD, do not just stop it once — it comes back on the next restart.
{% endhint %}

## The console says `framework: none`

The HUD could not find your framework. Job, gang, cash, bank, hunger and thirst will be blank; everything else still works.

| Cause                          | Fix                                                    |
| ------------------------------ | ------------------------------------------------------ |
| Framework starts after the HUD | Put `ensure qbx_core` above `ensure dm-hud`            |
| Renamed framework resource     | The HUD looks for `qbx_core`, `qb-core`, `es_extended` |
| It genuinely is standalone     | Nothing to fix. This is correct                        |

## Hunger and thirst sit at 100

The HUD reads these from your framework's metadata. If another script owns them, point the HUD at it with a [provider](/devmosaic/resources/devmosaic-dm-hud/configuration.md#handing-a-feature-to-your-own-script), or have that script push values with `setVital`.

## Fuel is always full

Eleven fuel scripts are detected automatically. If yours is not one of them, the HUD falls back to GTA's own fuel, which barely moves.

Set `DashCfg.debug = true` and restart — the console prints which fuel script it found.

## The seatbelt alarm will not stop

The alarm follows the seatbelt state. If you use your own seatbelt script, the HUD does not know you buckled up unless you tell it:

```lua
DashCfg.providers = {
    seatbelt = {
        get = function() return exports['my-seatbelt']:IsBuckled() end,
        toggle = function() exports['my-seatbelt']:Toggle() end,
    },
}
```

Or turn the sound off entirely in `shared/defaults.lua`:

```lua
sound = { beltAlarm = false },
```

## No speed limit sign appears

**Streets you have not listed show no sign.** That is by design.

```lua
DashCfg.zones = {
    ['Vinewood Blvd'] = 35,
}
```

To find the exact names, set `DashCfg.debug = true` and drive — each street prints to F8 as you enter it.

Also check the sign is not turned off: `F7` → Cars → Speed limit sign.

## The sign shows in the wrong place

It sits at the minimap's corner by default, and can be moved on its own in the layout editor. `F7` → Adjust layout → drag it.

## A setting I changed did nothing

{% hint style="danger" %}
**The most likely cause:** you edited `shared/defaults.lua` for one of the eight settings that are inherited from `shared/config.lua`.
{% endhint %}

Units, minimap shape, minimap zoom, on-foot map, in-vehicle map, north blip and dim screen all live in `config.lua`. Editing them in `defaults.lua` does nothing — the config value overwrites it. See [What players start with](/devmosaic/resources/devmosaic-dm-hud/defaults.md).

The second most likely cause: **the player already has a saved setting**, which always beats your default. They fix it with **Restore defaults** in the settings menu.

## A setting is greyed out

Something has locked it — either `DashPolicy.locked`, `DashPolicy.forced` in `shared/policy.lua`, or `DashCfg.locked` in `shared/config.lua`. Check all three. Remember that locking a group locks everything inside it.

## The HUD draws over another script's menu

```lua
DashCfg.nuiZIndex = 0
```

`0` puts the HUD underneath. If it still covers something, that script is setting its own layer — raise the number until it sits right, or set `false` to leave the layer untouched.

## The map moves when players change their safe zone

```lua
DashCfg.minimap = {
    ignoreSafeZone = true,
}
```

The layout is measured at 100% safe zone. Leave this `true`.

## Text is missing or shows as boxes

| Language                  | Cause                                                                                        |
| ------------------------- | -------------------------------------------------------------------------------------------- |
| Japanese, Korean, Chinese | These use the player's system fonts. Missing boxes mean their Windows install lacks the font |
| Anything else             | Bundled. Report it — it should never happen                                                  |

Arabic, Russian, Greek, Polish, Czech and Turkish all ship with their fonts.

## A partial translation leaves gaps

It cannot. Missing keys fall back to English automatically, so the worst case is a mixed-language interface, never a blank one.

## Frame rate drops

| Try                                       | Where                             |
| ----------------------------------------- | --------------------------------- |
| Lower the performance mode                | `F7` → General → Performance mode |
| Replace an animated logo with a still one | `DashCfg.logo`                    |
| Turn off modules you do not use           | `DashCfg.modules`                 |
| Turn debug off                            | `DashCfg.debug = false`           |

{% hint style="warning" %}
An animated `.gif` logo repaints constantly for every player. It is the most common self-inflicted performance problem.
{% endhint %}

## Players lost their layout after an update

Their saved layout is on their own machine, keyed to the resource. It survives updates. If it genuinely reset, they can rebuild it in seconds with `F7` → Adjust layout → Presets.

## A bar I added does not appear

| Check                | Fix                                                |
| -------------------- | -------------------------------------------------- |
| Registered too early | Wait for `GetResourceState('dm-hud') == 'started'` |
| `get` returns `nil`  | Return a number, or `0`                            |
| Hidden by policy     | Look for `'vitals.yourId'` in `shared/policy.lua`  |
| Range hides it       | A value outside its display range hides the bar    |

See [Adding your own](/devmosaic/resources/devmosaic-dm-hud/extending.md).

## Still stuck

Set `DashCfg.debug = true`, restart, and read the F8 console. It prints framework detection, fuel script detection, provider results and every street name you drive onto.

{% hint style="danger" %}
Set it back to `false` before you go live. Every player sees debug output in their own console.
{% endhint %}