Troubleshooting

Startup order

legacy-lib must start before any resource that depends on it. Other Legacy Scripts resources will error on exports or fail to start otherwise.
init.lua must load last within legacy-lib itself — it registers exports for Framework, Banking, Inventory, Store, Target, which must already exist as globals from earlier bridge files. If the manifest load order changes, exports can register as nil/empty tables.
modules/framework/_default.lua must load first among framework files so later bridges only overwrite individual functions rather than leaving others nil.

Banking

Setting LibConfig.Banking = 'auto' can let the weaker Renewed-Banking bridge win the race against legacy-banking, because legacy-banking also self-provides as Renewed-Banking in its own manifest. Only legacy-banking fully supports IBANs and SocietyTransfer (needed by legacy-bossmenu) — don't set this to 'auto' or 'Renewed-Banking' without checking dependents.
qb-banking and Renewed-Banking bridges always return { ok = false, reason = 'not_supported' } for SocietyTransfer, and blank iban/accountNumber fields for GetSocietyAccount — these are stubs, not real data.
Pinning LibConfig.Banking to an exact resource name that isn't actually running leaves Banking stuck on the no-op default, since no other bridge is allowed to bind.
legacy-banking's bridge always starts after legacy-lib (it depends on it) — its bridge relies on the onResourceStart re-bind, not the initial GetResourceState check, to bind correctly.

Framework

qbx_core silently takes priority over qb-core if both are running.
qb-core.lua and qbx_core.lua both call exports['qb-core']:GetCoreObject() — even the QBox bridge depends on the qb-core resource/export existing.
Framework.SetPlayerMetadata only exists on the qb-core/qbx_core bridges — calling it under ESX or the default bridge will error as a nil field.
Account name translation ('cash' vs 'money') is implicit and framework-specific inside Framework.GetAccountBalance/AddAccountBalance/RemoveAccountBalance — bypassing Framework.* and calling the underlying framework directly with the wrong literal name will look up the wrong balance.
Offline job-management paths (SetEmployeeGrade, FireEmployee, GetEmployees) run raw SQL against framework-specific tables/columns with no schema validation — renamed/migrated tables will silently fail or return wrong data.

Inventory

Only one inventory bridge binds; ox_inventory's bridge file does not guard against overwriting an already-bound bridge, so if ox_inventory is started it always wins regardless of load order.
If no supported inventory is running, Inventory.AddItem/RemoveItem/RegisterUsableItem return false/log errors rather than throwing — check return values, don't assume success.
Metadata support differs per bridge: only ox_inventory reliably uses metadata for add/remove; qb-inventory/qs-inventory ignore it on RemoveItem.
Stash functions (RegisterStash, SearchStash, AddStashItem, RemoveStashItem) only exist on the ox_inventory bridge — calling them under any other bridge will error (not just no-op).
Inventory.GetImagePath strips a trailing .png before rebuilding the path — pass the raw item name, not a pre-built path.

Client (Target / Inventory)

Only the first detected Target/inventory system wins if multiple are running — there is no priority logic beyond load order in the manifest.
_default.lua fallbacks for Target/InventoryClient no-op with only a console warning — failures are silent in-game unless you're watching the console.
GetLogo() returns nil if LibConfig.LogoPath is unset/empty or the file can't be loaded — callers must handle nil.
Server-only exports (GetLocale, SendWebhook, CheckVersion, Store) don't exist on the client — calling them client-side fails outright.

Store (JSON config)

Store.Read/Write/ReadOrMigrate are server-only (use LoadResourceFile/SaveResourceFile).
Always pass GetCurrentResourceName() as the resource argument — passing 'legacy-lib' reads/writes inside legacy-lib's own folder instead of your resource's.
Store.Read distinguishes 'absent' from 'corrupt' — don't treat a corrupt file as empty and overwrite it; Store.Write independently refuses to clobber a file that exists but fails to parse.
Store returns plain tables, not an object — there's no Store:Load()-style API since metatables don't survive the FiveM export table-copy boundary. Mutations aren't auto-persisted; you must call Store.Write explicitly.
Only one backup (<path>.bak) is kept, and only when the previous file both parses and differs from the new content — it is not a version history.

Webhooks / Version check

SendWebhook silently no-ops if url is nil/'' — no error, no log, so a blank webhook URL looks identical to a working no-op.
CheckVersion/Lib.CheckVersion silently does nothing if LibConfig.VersionCheckURL is empty or resourceName/currentVersion are missing — enable LibConfig.Debug to see why a check isn't reporting.
The remote version JSON must be keyed exactly by the resource name being checked, or CheckVersion reports "no version info found" rather than an error.

General

LibConfig.Debug must be true to see any [Legacy Lib] ... confirmation prints (module registration, bridge loaded, bind confirmations) — silence at startup does not necessarily mean failure.
Support for this resource is Discord-only (https://discord.gg/P2Jujr3Khh) — there is no issue tracker.

Startup order

legacy-lib must start before any resource that depends on it. Other Legacy Scripts resources will error on exports or fail to start otherwise.

init.lua must load last within legacy-lib itself — it registers exports for Framework, Banking, Inventory, Store, Target, which must already exist as globals from earlier bridge files. If the manifest load order changes, exports can register as nil/empty tables.

modules/framework/_default.lua must load first among framework files so later bridges only overwrite individual functions rather than leaving others nil.

Banking

Setting LibConfig.Banking = 'auto' can let the weaker Renewed-Banking bridge win the race against legacy-banking, because legacy-banking also self-provides as Renewed-Banking in its own manifest. Only legacy-banking fully supports IBANs and SocietyTransfer (needed by legacy-bossmenu) — don't set this to 'auto' or 'Renewed-Banking' without checking dependents.

qb-banking and Renewed-Banking bridges always return { ok = false, reason = 'not_supported' } for SocietyTransfer, and blank iban/accountNumber fields for GetSocietyAccount — these are stubs, not real data.

Pinning LibConfig.Banking to an exact resource name that isn't actually running leaves Banking stuck on the no-op default, since no other bridge is allowed to bind.

legacy-banking's bridge always starts after legacy-lib (it depends on it) — its bridge relies on the onResourceStart re-bind, not the initial GetResourceState check, to bind correctly.

Framework

qbx_core silently takes priority over qb-core if both are running.

qb-core.lua and qbx_core.lua both call exports['qb-core']:GetCoreObject() — even the QBox bridge depends on the qb-core resource/export existing.

Framework.SetPlayerMetadata only exists on the qb-core/qbx_core bridges — calling it under ESX or the default bridge will error as a nil field.

Account name translation ('cash' vs 'money') is implicit and framework-specific inside Framework.GetAccountBalance/AddAccountBalance/RemoveAccountBalance — bypassing Framework.* and calling the underlying framework directly with the wrong literal name will look up the wrong balance.

Offline job-management paths (SetEmployeeGrade, FireEmployee, GetEmployees) run raw SQL against framework-specific tables/columns with no schema validation — renamed/migrated tables will silently fail or return wrong data.

Inventory

Only one inventory bridge binds; ox_inventory's bridge file does not guard against overwriting an already-bound bridge, so if ox_inventory is started it always wins regardless of load order.

If no supported inventory is running, Inventory.AddItem/RemoveItem/RegisterUsableItem return false/log errors rather than throwing — check return values, don't assume success.

Metadata support differs per bridge: only ox_inventory reliably uses metadata for add/remove; qb-inventory/qs-inventory ignore it on RemoveItem.

Stash functions (RegisterStash, SearchStash, AddStashItem, RemoveStashItem) only exist on the ox_inventory bridge — calling them under any other bridge will error (not just no-op).

Inventory.GetImagePath strips a trailing .png before rebuilding the path — pass the raw item name, not a pre-built path.

Client (Target / Inventory)

Only the first detected Target/inventory system wins if multiple are running — there is no priority logic beyond load order in the manifest.

_default.lua fallbacks for Target/InventoryClient no-op with only a console warning — failures are silent in-game unless you're watching the console.

GetLogo() returns nil if LibConfig.LogoPath is unset/empty or the file can't be loaded — callers must handle nil.

Server-only exports (GetLocale, SendWebhook, CheckVersion, Store) don't exist on the client — calling them client-side fails outright.

Store (JSON config)

Store.Read/Write/ReadOrMigrate are server-only (use LoadResourceFile/SaveResourceFile).

Always pass GetCurrentResourceName() as the resource argument — passing 'legacy-lib' reads/writes inside legacy-lib's own folder instead of your resource's.

Store.Read distinguishes 'absent' from 'corrupt' — don't treat a corrupt file as empty and overwrite it; Store.Write independently refuses to clobber a file that exists but fails to parse.

Store returns plain tables, not an object — there's no Store:Load()-style API since metatables don't survive the FiveM export table-copy boundary. Mutations aren't auto-persisted; you must call Store.Write explicitly.

Only one backup (<path>.bak) is kept, and only when the previous file both parses and differs from the new content — it is not a version history.

Webhooks / Version check

SendWebhook silently no-ops if url is nil/'' — no error, no log, so a blank webhook URL looks identical to a working no-op.

CheckVersion/Lib.CheckVersion silently does nothing if LibConfig.VersionCheckURL is empty or resourceName/currentVersion are missing — enable LibConfig.Debug to see why a check isn't reporting.

The remote version JSON must be keyed exactly by the resource name being checked, or CheckVersion reports "no version info found" rather than an error.