Troubleshooting

Cards & ATM

• Cards were ordered/charged but invisible to the ATM. The ATM only recognizes a card if the matching debit_card inventory item is present in the wallet with metadata (metadata.card_id). If your inventory bridge's AddItem silently drops metadata (e.g. debit_card is set stack = true and merges stacks), cards vanish from the ATM/wallet view even though the DB row and charge went through. Turn on Config.Debug and watch for matchingSlotsAfter=0 logs in server/cards.lua.
• "ATM Init SQL error" on boot/use. This points at needing sql/migrate-pin-plaintext.sql. PINs are stored in plaintext by design; a database still expecting pin_hash/pin_salt will error rather than fail gracefully.
• PINs are never hashed, even though LB.HashPin/LB.VerifyPin/LB.GenerateSalt exist in server/server.lua. The card PIN flow (LB.Cards.ChangePin/VerifyPin) compares plaintext directly. This is an intentional threat-model decision (protects against other players, not server operators) — do not attempt to "fix" it by re-hashing without also removing the legacy-banking:viewPin feature.
• ATM withdrawal rejected with reason = 'denomination'. The requested amount must be an exact multiple of Config.AtmDenomination. Validate this client-side before submitting a custom amount.
• ATM target prompt appears on props you didn't intend. Config.AtmModels matches by model globally — any world prop using one of those models anywhere on the map gets the "Use ATM" option, not just the ones you placed.
• ATM permanently unreachable, one warning printed at startup. client/atm.lua requires the legacy-lib target bridge to expose Target.AddModel. This is checked once on a 1000ms delayed thread with no retry — an outdated legacy-lib means ATMs never work until you restart after fixing legacy-lib.

Transfers & accounts

• Recipient lookup fails for a phone number or citizen id. This is by design — legacy-banking:resolveRecipient / LB.Transfer.ResolveRecipient only accept IBAN strings. Anything else returns nil, 'bad_iban'.
• Transfer fee seems to "disappear". LB.Transfer.Send debits amount + Config.Transfer.Fee from the sender but only credits the recipient with amount — the fee is not deposited anywhere.
• Ledger shows a debit + a refund instead of a clean rollback. If crediting the recipient fails after the sender was already debited, the sender is refunded automatically, but the refund is logged as a plain Other-category transaction, not a reversal of the original transfer.
• Non-boss employees can't transfer out of a society account, and read-only/deposit-only shared members can't be used as a transfer source. This is enforced by design (LBCanWithdraw for shared, live boss-flag check for society) — verify your framework bridge reports job/boss status correctly if a legitimate boss is denied.
• Offline-recipient transfers depend on your framework's players.money JSON schema. Crediting an offline player writes directly to that column; if your framework's schema differs (not qbx_core-style JSON), this will break.

Society / job accounts

• LB.Society.AddMoney/RemoveMoney silently return false (no error thrown) if amount <= 0 or jobName is nil — always check the boolean return.
• Calling LB.Society.EnsureExists again with a different jobLabel does not update an already-existing account's label.
• Resource-name collision risk: this resource provides 'Renewed-Banking'. Running the real Renewed-Banking resource alongside legacy-banking will collide.

Locations / admin tool

• Bank locations don't reflect SQL changes after boot. legacy_banking_locations is only read once at first boot to migrate legacy rows into data/locations.json (via legacy-lib's Store). After that, all reads/writes go through the JSON store — editing the SQL table directly has no effect. Use legacy-banking:saveLocation/deleteLocation or the /bankmanage (Config.AdminCommand) tool instead.
• Hand-editing data/locations.json. It has a nextId counter; editing IDs without updating it risks ID collisions.
• Ped preset doesn't appear as configured. Non-freemode Config.PedPresets entries are ambient GTA peds that may be missing on heavily modded servers. Placement silently falls back to mp_m_freemode_01 if the model fails to load (~2s timeout) — no error is shown.
• Client-side ped/blip leak on crash-restart. client/locations.lua's cleanup only runs on a normal onResourceStop for this resource — a hard crash-restart path can leak spawned peds/blips.
• Remember to broadcast legacy-banking:syncLocations() after any server-side change to location data outside the built-in save/delete callbacks, or connected clients won't refresh.

Webhooks

• A configured webhook never fires and there's no error. Config.Webhooks[eventKey] must be an empty string '' to disable — there's no separate boolean toggle. Conversely, a malformed (non-empty) URL will likely throw rather than silently no-op, so double-check URLs when enabling.

lb-phone

• The phone app doesn't appear. Registration happens entirely at runtime via exports['lb-phone']:AddCustomApp (not a static Config.CustomApps table in this resource) — it silently fails if AddCustomApp isn't available on your installed lb-phone build, or if lb-phone isn't started.
• Server pushes to the phone don't arrive. LB.Push → exports['lb-phone']:SendCustomAppMessage only reaches a player if they currently have the phone app open, and hard-depends on lb-phone being installed/running — not just legacy-lib/ox_lib/oxmysql.
• Phone UI works in browser preview but not in-game (or vice versa). phone/src/nui.ts relies on window.fetchNui/window.onNuiEvent injected by the lb-phone host; outside lb-phone it falls back to a browser-preview shim meant only for local dev, which won't reach the real server.
• Remember: phone NUI calls are prefixed with phone: internally, and the phone's server callbacks live under the separate legacy-banking:phone:* namespace — they do not share names with the desktop UI's NUI handlers or callbacks.

Config sync

• UI category filter doesn't match server-tagged categories. Config.Categories must be kept manually in sync with web/src/utils/categories.ts.
• Config.Colors.Green doesn't reflect what you set. It's overridden at runtime by legacy-lib's GetAccentColor export if present, to keep suite-wide theming consistent.