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

# Troubleshooting

> Most problems show themselves in the server console — filter for [nex_bossmenu] first. Failed mutations log in red with the failure reason.

Most problems show themselves in the **server console** — filter for `[nex_bossmenu]` first. Failed mutations log in **red** with the failure reason.

## Common issues

| Problem                                                       | Fix                                                                                                                                                                                                                                                                                                                                          |
| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **"You are not authorized."** on `/bossmenu_admin`            | You're not `group.admin` / `group.superadmin`, not in the framework permission list (`esxGroups` / `qbGroups`), and not ACE-allowed for any path in `Config.Admin.acePermissions`. Most txAdmin admins are `group.admin` by default — double-check your `permissions.cfg`. See [Commands → Permissions](/nex_bossmenu/commands#permissions). |
| **"You are not the boss of this society."**                   | Your job grade isn't a configured boss grade. Either set `isboss = true` on the grade in your framework's shared jobs config *(QB / Qbox)*, or add your grade's `name` to `Config.BossGradeNames` *(any framework)*.                                                                                                                         |
| **Hire fails with "esx setJob did not stick"**                | The target job or grade `0` doesn't exist in `ESX.Jobs` at runtime. Check your `jobs` / `job_grades` tables actually have a `grade = 0` row for that job. ESX's `setJob` silently warns and refuses to mutate otherwise — the bridge does a readback so this surfaces as an error instead of looking like a success.                         |
| **"Society account write failed."** on QB / Qbox              | Your society backend (Renewed-Banking / qb-management) isn't started, or doesn't recognise the job. Make sure the banking resource starts **before** `nex_bossmenu` — the export check happens at the first balance call, not at boot.                                                                                                       |
| **Markers don't appear after promoting someone mid-session**  | The client polls the server-side job every `Config.JobPollMs` (2s default). Lower it for faster reaction.                                                                                                                                                                                                                                    |
| **Hire button greys out the moment I click it**               | The candidate moved out of `Config.HireDistance` (5m default) between menu open and click. Walk closer and try again. The check is re-run server-side at click time.                                                                                                                                                                         |
| **"Insufficient funds" but the player clearly has the money** | `Config.PlayerAccount` is set to `bank` and the player only has cash, or vice versa. Pick the account your framework actually credits payday into.                                                                                                                                                                                           |
| **Marker draws but no `[E]` prompt appears**                  | `Config.Interaction.mode = 'target'` but neither `ox_target` nor `qb-target` is running — the resource falls back to `textui` automatically, but you might be outside `Config.InteractDistance` (1.6m default). Walk closer.                                                                                                                 |
| **Eye-target option doesn't show**                            | Same as above — target script not running, or the marker job doesn't match your job. The option is gated by both.                                                                                                                                                                                                                            |
| **Money disappeared on a failed transaction**                 | Should never happen — every society write has a refund-on-failure path. If you can reproduce this, file a ticket with the server console log. Bridge `AddSociety` / `RemoveSociety` must return `false` on failure for the refund path to fire — relevant for [custom frameworks](/nex_bossmenu/custom-frameworks).                          |
| **Society balance shows 0 for an existing job**               | On ESX, the `society_<jobname>` row didn't exist before this resource was installed. The bridge auto-seeds it the first time the balance is read — open the menu once, the row is created, balance updates.                                                                                                                                  |
| **Migration warning on first boot**                           | Working as intended. The schema bootstrap atomically renames `boss_menu_locations` → `nex_bossmenu` and adds the `label` column if missing. Your placed markers carry over with no manual SQL.                                                                                                                                               |

## Permissions debug

To see exactly which check granted (or denied) admin access:

1. Look at the server console when running `/bossmenu_admin`.
2. The check order is: ACE permissions in `Config.Admin.acePermissions` → framework group in `esxGroups` / `qbGroups` → framework's built-in `IsAdmin`.
3. The first match wins.

If you're locked out despite being `group.admin`, your `permissions.cfg` is probably stripping the default txAdmin grant. Re-add it:

```
add_ace group.admin command.bossmenu_admin allow
```

## Before opening a support ticket

Please include:

1. Server console output filtered for `[nex_bossmenu]`.
2. Your framework (Qbox / QBCore / ESX) and version.
3. Your society backend (`Renewed-Banking`, `qb-management`, `qb-banking`, or `esx_addonaccount`) and load order.
4. The job that's affected and a sample of its grade list.
5. What you did and what you expected to happen.

See [Support & contact](/general/support).