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

# Troubleshooting

> Fix common atlasBridge issues — load order, provider detection, UI, theme, and Discord permissions.

Most `atlasBridge` issues trace back to one of five causes: the resource name, start order, provider detection, missing NUI files, or an incorrect convar. Work top to bottom.

<Tip>
  Add `setr atlas:debug "true"` while diagnosing — it prints adapter selection and networking detail. Turn it off before production.
</Tip>

## `Bridge` is nil / load order

If a consumer script errors with `Bridge` being `nil`, the bridge is loading after that script.

* Confirm the folder is named exactly `atlasBridge`. Consumers load `@atlasBridge/init.lua`; a renamed folder breaks that path.
* Confirm the consumer's `fxmanifest.lua` has both lines:

```lua theme={null}
dependency 'atlasBridge'
shared_script '@atlasBridge/init.lua'
```

* Confirm `ensure atlasBridge` runs **before** the dependent resource in your `server.cfg`.

## Framework or inventory not detected

Auto-detection only sees resources that are already started, and framework/inventory are detected **once at boot**.

Start dependencies before the bridge:

```cfg theme={null}
ensure ox_inventory
ensure qbx_core
ensure atlasBridge
```

Or force the provider so order no longer matters:

```cfg theme={null}
setr atlas:framework "qbx"
setr atlas:inventory "ox"
```

With debug on, the console prints the selected adapter — for example `[Framework] server adapter: es_extended`. If it reads `_default` when you expected a framework, detection missed it.

## Money or inventory actions fail

* The framework/inventory provider is correct (check the adapter line with debug on).
* Account names are normalized: `cash`, `bank`, or `dirty` — not your framework's raw names.
* Item keys exist in your inventory and match the Atlas resource's config.
* The player has space/weight if your inventory enforces capacity.
* On a **custom** adapter: if the line reads `_default`, your stub errored at load and the no-op default is running. Fix the load error. See [Custom Framework](/atlas-bridge/custom-framework#pitfalls).

## Notifications or menus do not show, or use the wrong provider

The bridge's own NUI is the **default**. `ox_lib` is only used if you opt in with `atlas:ui "ox"`.

* `atlasBridge/web/dist/index.html` exists (required for the bridge's own NUI).
* If you forced `ox`, confirm `ox_lib` is started — and started **before** the bridge.
* A per-subsystem override (`atlas:ui:notify`, `atlas:ui:progress`, …) wins over the global `atlas:ui`; check you did not pin a subsystem to a provider that is not running.

Safe fallback — force the bridge's own zero-dependency NUI everywhere:

```cfg theme={null}
setr atlas:ui "own"
```

## Target prompts do not appear

* The target provider reads `atlas:target` — **not** `atlas:ui:target`.
* With `auto`, the bridge resolves `ox_target → qb-target → own`. Force `own` to use the bridge's built-in prompts:

```cfg theme={null}
setr atlas:target "own"
```

## Death detection does not trigger

The bridge detects most deaths automatically. If an Atlas resource does not react when a player dies:

* Confirm `atlasBridge` starts before the Atlas resource.
* Test with the default setup first.
* If your death/ambulance system uses its own event, route it through the bridge:

```cfg theme={null}
setr atlas:deathEvent "baseevents:onPlayerDied"
```

## Discord profiles do not load

* The token is set with `set`, not `setr`.
* The guild ID is correct and the bot is a member of that guild.
* The bot has permission to read members and roles.
* With debug on, the bridge logs `Discord enabled as <bot> (guild ...)` at startup. If it logs `invalid token/guild ... module disabled`, the token or guild is wrong.

```cfg theme={null}
set atlas:discord:token "YOUR_BOT_TOKEN"
set atlas:discord:guild "YOUR_GUILD_ID"
```

## Permissions or Discord roles not granting

If `Bridge.Permissions.Has(src, node)` returns `false` when it should grant:

* **Register both maps.** A node only resolves through a label that has both a role ID (`Bridge.Discord.RegisterRoles`) **and** that node (`Bridge.Permissions.RegisterNodes`). The bridge ships with nothing registered — until you register them, every node is denied.
* **The label, not the role ID, goes in `RegisterNodes`.** The key in `RegisterNodes` (e.g. `admin`) is the label; the real Discord role snowflake lives only in `RegisterRoles`.
* **Discord must be enabled** for role-granted nodes — see the section above. (ACE-granted nodes work without Discord.)
* **The player must actually hold the role** in the guild, and have a `discord:` identifier (the Discord scope must be authorized on connect).
* **ACEs are checked first.** If an unexpected player passes, check for a server ACE granting the node.

See [Permissions](/atlas-bridge/developer/permissions) for the full two-step flow.

## Theme color looks wrong or does not apply

* `atlas:theme:color` accepts any valid hex; the default is `#F487F4`. An invalid hex is ignored.
* The server color drives both UI accents and marker-prop recolor, and is applied live.
* **A per-player override wins over the server default.** If a player's UI is the wrong color, they may have set their own accent via `Bridge.Theme.Set` (it persists on their client). Have them run a reset, or call `Bridge.Theme.Reset()`, to fall back to the server color.
* `Bridge.Theme.Set(hex)` returns `false` for an invalid hex and changes nothing — check the return value in your picker.

```cfg theme={null}
setr atlas:theme:color "#F487F4"
```

See [Theming](/atlas-bridge/theming) for the per-player picker flow.

## Debugging process

<Steps>
  <Step title="Enable debug">
    Add `setr atlas:debug "true"`.
  </Step>

  <Step title="Restart in order">
    Restart framework, inventory, target/UI, then `atlasBridge`, then Atlas resources.
  </Step>

  <Step title="Read the first error">
    Fix the first bridge error before chasing errors from dependent resources.
  </Step>

  <Step title="Force providers if needed">
    If detection is wrong, set explicit convars.
  </Step>

  <Step title="Turn debug off">
    Set `setr atlas:debug "false"` before production.
  </Step>
</Steps>