# Troubleshooting (/docs/orbit-studios-resources/orbit-dynamichud-v2/troubleshooting)



# Troubleshooting [#troubleshooting]

Start with the client and server consoles. Resolve the first error before debugging dependent UI behavior.

<Accordions>
  <Accordion title="The HUD or control panel does not appear">
    Confirm `ox_lib`, your framework, `orbit-lib`, and `orbit-dynamichud-v2` start in that order. Check that the relevant entry in `Config.ControlPanel.EnabledModules` is enabled, then run `/restarthud`. Also verify that another resource is not calling `toggleHud(false)` or setting the replicated `hud:showHud` player state to `false`.
  </Accordion>

  <Accordion title="A command is missing or has a different name">
    Command names come from the active locale and each command has an `enabled` switch in config. Verify `setr ox:locale`, the matching value under `commands` in the locale JSON, and the command entry in `Config.Commands` or `server/config.lua`. Restart the resource after changing either file.
  </Accordion>

  <Accordion title="Money, needs, or stress do not update">
    Verify the selected framework and its compatibility events. ESX uses events such as `esx:setAccountMoney` and `esx_status:onTick`; QB/QBX resources commonly use `hud:client:OnMoneyChange`, `hud:client:UpdateNeeds`, and `hud:client:UpdateStress`. Stress can also be supplied through `LocalPlayer.state.stress`. Enable the corresponding entries in `Config.EnabledValues`.
  </Accordion>

  <Accordion title="Seatbelt, cruise control, nitrous, or death state does not update">
    Set the supported state bags rather than changing UI files. The relevant player keys are `seatbelt`, `cruiseControl`, `hud:deathState`, and `qbx_medical:deathState`; vehicle nitrous uses `nitro` and `nitroFlames`. Compatibility events are listed on the Events & State Bags page.
  </Accordion>

  <Accordion title="Text UI, progress bars, or skill checks do not open">
    Only one progress bar and one skill check can run at a time. Check `progressActive()` or `skillCheckActive()`, and make sure the previous resource cleans up on stop. For Text UI, `showTextUI` replaces the current prompt and `hideTextUI` closes it. Use the exports documented in Interface API instead of sending NUI messages directly.
  </Accordion>

  <Accordion title="A progress bar immediately cancels or never completes">
    Check its state restrictions (`useWhileDead`, `allowRagdoll`, `allowSwimming`, `allowCuffed`, and `allowFalling`) and verify the animation dictionary, scenario, prop model, and bone. The export is blocking and returns `true` only on completion. A resource stop, explicit cancellation, failed condition, or watchdog timeout returns `false`.
  </Accordion>

  <Accordion title="Notifications do not show">
    Call the `notify` export or trigger `orbit-dynamichud:notify` on the client. A server script must use `TriggerClientEvent('orbit-dynamichud:notify', source, data)`. Visible notifications with the same explicit `id` are deduplicated, so omit the ID or use a new one when repeated messages should stack.
  </Accordion>

  <Accordion title="Music works locally but not in phone or vehicle mode">
    Confirm the music module is enabled and `onlyLocalMusic` is `false`. Headphone mode is intentionally frontend-only. Phone and car modes require the server music logic and current player/vehicle state. Car mode cannot be selected outside a vehicle.
  </Accordion>

  <Accordion title="Settings sharing does not load presets">
    Start `oxmysql` before `orbit-dynamichud-v2`, verify the database credentials, and check that Settings Share and the requested operation are enabled in config. Public discovery, private presets, manual import, share codes, moderation, and thumbnails have separate switches. The resource creates and migrates its tables automatically when database access succeeds.
  </Accordion>

  <Accordion title="A settings preset or manual JSON import is rejected">
    Presets use a strict allowlist schema: missing keys, unknown keys, invalid enum values, unsafe names, and out-of-range values are rejected on both client and server. Preset names are limited to 30 normal text characters. Export a current preset and compare its structure instead of editing unknown fields into an older payload.
  </Accordion>

  <Accordion title="Settings screenshots are unavailable">
    Screenshot thumbnails require `Config.ControlPanel.settingsShare.thumbnails = true`, a valid server-side FiveManage API key, and the resource selected by `Config.SettingsShareServer.thumbnail.captureProvider` (`screenshot-basic` or `screencapture`) to be started. The provider reported to the client must match the configured resource. The upload cooldown applies before screenshot preparation, so repeated attempts can be rejected before any frame is taken. Without screenshot support, presets use the status and speedometer fallback preview.

    Enable `Config.Debug` temporarily and check the client F8 console for provider, HUD snapshot, DUI, capture, or upload errors. Check the server console for missing API credentials, FiveManage presigned-URL failures, invalid returned hosts, expired tickets, and database errors. The capture path renders the actual HUD through a capture-only DUI, draws it over the game with the minimap enabled, then restores the previous HUD/radar state. A failure in any stage rejects only the custom thumbnail; save the preset without one to use the fallback preview.
  </Accordion>

  <Accordion title="Manual onboarding does not open">
    Confirm `Config.Onboarding.enabled = true`, `Config.Onboarding.trigger = "manual"`, and `Config.SettingsLocked = false`. Trigger `orbit-dynamichud:client:openOnboarding` only after the player and DynamicHUD 2.0 client are loaded. The event intentionally does nothing after that client has completed onboarding. Use the enabled `/onboarding` command to force a support/test run; if the command opens but the event does not, the player has normally already completed onboarding or the integration is firing too early. See the Onboarding guide for complete examples.
  </Accordion>

  <Accordion title="Automatic onboarding keeps waiting">
    Automatic onboarding starts its five-second Text UI notice only after normalized player data reports a logged-in character and no other NUI or Text UI owns the interface. Opening a clothing menu, spawn selector, or another prompt hides DynamicHUD 2.0's notice and resets the full delay. Close the competing interface and leave focus free for five uninterrupted seconds. Use manual mode when another resource has a more reliable final-ready event.
  </Accordion>

  <Accordion title="Private share codes stop working">
    Share codes are intentionally temporary. Settings codes expire after `Config.SettingsShareServer.privateShareTtlSeconds` (15 minutes by default). Each player can have one active settings code and one active playlist code; creating a replacement invalidates the old code. Codes are also removed when their owner disconnects and are lost when the resource or server restarts.
  </Accordion>

  <Accordion title="Car control is empty or unavailable">
    Car Control only opens while the player is in a supported vehicle and requires `Config.ControlPanel.carControl.enabled = true`. With `carControl.mode = "owner"`, only the current FiveM network owner may use controls. With `"realistic"`, the driver controls everything while passengers are limited to seat changes and the door/window beside their seat. Individual actions are also limited by vehicle type, seat, driver permission, available doors/windows, and backend validation. Neon controls require a compatible car and `Config.ControlPanel.carControl.neon = true`.
  </Accordion>

  <Accordion title="Waypoint color or map data is stale">
    Set a new waypoint and allow the next HUD update to resolve its color. Waypoint color is fetched once per waypoint rather than every frame. If compass data never changes, verify that the dynamic bar navigation value and the appropriate layout component are enabled.
  </Accordion>
</Accordions>

For callable APIs and integration names, use [Exports](/docs/orbit-studios-resources/orbit-dynamichud-v2/exports) and [Events & State Bags](/docs/orbit-studios-resources/orbit-dynamichud-v2/events).