> ## Documentation Index
> Fetch the complete documentation index at: https://docs.awokenlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> The things that go wrong, and what each one actually means.

<AccordionGroup>
  <Accordion title="The menu opens but nothing happens, or the resource looks dead" icon="lock">
    The folder has been renamed. The resource checks its own folder name at start and goes completely inert if it does not match, which is how we stop resellers passing it off as their own.

    Rename the folder back to exactly `awoken_pausemenu` and restart it. There is a red banner in your server console saying the same thing.
  </Accordion>

  <Accordion title="My HUD is still on screen behind the menu" icon="eye">
    The menu hides the game's own HUD, minimap, weapon and notifications. A HUD drawn in its own NUI is a separate resource and no native reaches it.

    Most HUDs hide themselves when `IsPauseMenuActive()` is true, and that never becomes true any more, because the native menu is what this replaces. Two ways out:

    1. If it has an export or an event of its own, call it from `client/hooks.lua`.
    2. If it has neither, read `LocalPlayer.state.pauseMenuOpen` on its side, in place of `IsPauseMenuActive()`.

    Every HUD with a published hide API is already handled without you doing anything. Today that is jg-hud. qb-hud, ps-hud and their forks expose nothing at all, so they are option 2.

    See [Exports and events](/resources/awoken-pausemenu/exports).
  </Accordion>

  <Accordion title="My inventory or emote menu opens over the pause menu" icon="keyboard">
    It should not. The menu takes the keyboard off the game entirely while it is open, which stops a `RegisterKeyMapping` hotkey reaching its own resource. If one still opens, that resource is not using a key mapping at all: it is polling raw input, and nothing here can stop it.

    ox\_inventory is a special case and is handled either way, through the `invBusy` state it checks itself. Pressing the key then gets ox\_inventory's own "cannot access inventory" notice rather than the inventory.
  </Accordion>

  <Accordion title="The portrait shows initials instead of a face" icon="user">
    The game renders headshots asynchronously and occasionally refuses outright. The fallback is drawn in the same circle so nothing shifts, and the next open tries again.

    If it never comes back, even after reopening, another resource is likely exhausting the game's headshot slots. Restart the resource to clear ours. If it is consistently slow rather than absent, raise `Config.PlayerInformation.portrait.timeoutMs`.
  </Accordion>

  <Accordion title="The face is too zoomed in, or the head sits oddly in the circle" icon="crop">
    `Config.PlayerInformation.portrait.zoom`. `1` is the texture exactly as the game rendered it, which already frames head and shoulders. The default of `1.08` only trims the margin.
  </Accordion>

  <Accordion title="Session and total playtime never appear" icon="clock">
    Total playtime is the only feature that uses the database, so check `oxmysql` is in your start order. The table builds itself on first start, so there is no SQL file to import.

    Both numbers hang off the bridge telling us a character has loaded. If the bridge cannot see your framework, check it started first: it works out what you run at load time, so anything starting after it is invisible to it. `Config.Debug` in the bridge prints what it picked.
  </Accordion>

  <Accordion title="Dirty money always reads zero" icon="money-bill">
    You are on QBCore or QBox with `type = 'account'`. Neither has a `black_money` account, so the lookup honestly returns nothing. Dirty money there is the marked bills item:

    ```lua config.lua theme={"dark"}
    dirtyMoney = { enabled = true, type = 'item', item = 'markedbills' },
    ```
  </Accordion>

  <Accordion title="The job grade is missing" icon="briefcase">
    We only ever show the framework's own label for a grade, never its internal name. A job whose grades carry no label shows no grade, which is better than putting `grade_3` on screen.

    Add a label to that grade in your framework's job config and it appears.
  </Accordion>

  <Accordion title="Opening the map shows the stock pause menu first" icon="map">
    It should not, and if it does you are on an older build. Opening the map is three steps: the frontend is hidden while it comes up, moved to the map page, and only then drawn. Backing out closes it straight back to our menu rather than stepping up into the stock one.

    Re-download the asset and replace the folder.
  </Accordion>

  <Accordion title="The console says 'Could not check for updates'" icon="rotate">
    The version file for this resource has not been published yet, or your server cannot reach `raw.githubusercontent.com`. It is a notice, not a fault: nothing about the resource depends on it.

    `Config.updateNotifications = false` silences the check and the banner together.
  </Accordion>
</AccordionGroup>

## Still stuck

<Card title="Support" icon="life-ring" href="/support">
  How to reach us, and what to include so the first reply is a useful one.
</Card>