Troubleshooting

​

Bridge is nil / load order

• 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:

dependency 'atlasBridge'
shared_script '@atlasBridge/init.lua'

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

​

Framework or inventory not detected

ensure ox_inventory
ensure qbx_core
ensure atlasBridge

setr atlas:framework "qbx"
setr atlas:inventory "ox"

​

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.

​

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

• 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.

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:

setr atlas:target "own"

​

Death detection does not trigger

• 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:

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.

set atlas:discord:token "YOUR_BOT_TOKEN"
set atlas:discord:guild "YOUR_GUILD_ID"

​

Permissions or Discord roles not granting

• 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.

​

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.

setr atlas:theme:color "#F487F4"

​

Debugging process