8 min read
Troubleshoot inventory updates
An inventory failure after an update can be a caller/API mismatch, invalid shared item, UI failure or storage migration problem. Identify which one before replacing scripts or changing a database.
The source baseline here is qb-inventory at dc3d07fc and qb-core at 9b3cddcc. It is not a statement that every older fork supports these calls. The acceptance checks are proposed in-game tests, not executed results.
Conceptual diagram; verify the behavior against your installed resource version.
Why is my QBCore inventory not opening?
First separate a missing input, a refused open request and a broken NUI. If the inventory key does nothing, compare the saved FiveM keybinding with the installed configuration. If the request reaches Lua but is refused, inspect player loading and busy state. If the cursor appears with a blank interface, inspect the first NUI JavaScript or asset error. Do not delete player data or force busy flags off to bypass these distinctions.
| Observation | Next check | Evidence of a fix |
|---|---|---|
| No response to the inventory key | Saved keybinding, configured command and whether the client resource loaded | The intended command reaches the installed handler |
| Cursor appears but inventory is blank | Manifest UI files, built assets, first NUI error and failed requests | UI loads and its open/close callbacks finish |
| Inventory refuses to open after an action | Read inv_busy; identify the operation that set it and its cancellation/cleanup path | Action completes or cancels, then normal opening works |
| Inventory only fails before character selection | Player-ready lifecycle and first character-loading failure | Normal opening after a completed login, without forcing readiness |
Missing LoadInventory or OpenInventory export | Provider name, startup error, execution side and installed API | Matching caller/provider works on clean startup and reconnect |
| Two inventory interfaces or repeated focus problems | Competing resources and duplicate key/command handlers | One inventory owns the action and releases focus on close |
For exact missing-export strings, use the export error reference. If switching inventory providers, follow the ox_inventory compatibility checks before touching stored items. These diagnostic additions were reviewed on 2026-11-13; the pinned qb-inventory source baseline below remains unchanged.
Evidence to collect
Record the commits for core, inventory and the first failing caller; the first server/F8 error including file and line; whether the problem affects all items or one item; and whether personal inventory, stash, trunk and shop behave differently. Record schema changes and local modifications separately from the downloaded resource version. Redact credentials and player records.
# Run separately inside each resource repository.
git rev-parse HEAD
git status --short
git diff --statA ZIP installation may have no Git history. Keep its release tag, source URL, download checksum and original archive instead of inventing a commit.
Safe diagnostic
| Symptom | First check | Do not do first |
|---|---|---|
QBCore:HasItem is deprecated | Find the caller of the old callback and its execution side | Globally replace every occurrence of HasItem |
Missing AddItem, OpenInventory or another export | Is the provider started, and does that exact commit export it on this side? | Rename the call until the error disappears |
| One new item is absent | Exact shared key/name and valid items.lua syntax | Recreate the inventory database |
| Inventory opens without the expected icon | image filename, capitalization and asset request | Treat the PNG as the item registration |
| Personal inventory works, stashes are empty | Old/new storage tables, identifiers and migration history | Run migrate.sql repeatedly |
| Key does nothing or UI remains stuck | F8/NUI error, keybinding, inv_busy, focus and competing inventory scripts | Force inv_busy = false for all players |
| Items vanish after reconnect | Missing shared definitions, save errors and persisted JSON | Delete the affected character |
Reproduce on staging with one minimized test character. Start from a working core/inventory pair, then introduce one caller or local change at a time. See load order, keybindings and oxmysql.
Fix
HasItem: match both the API and the execution side
An old client pattern you may find is:
-- Legacy callback pattern: identify its callers; do not add it to new code.
QBCore.Functions.TriggerCallback('QBCore:HasItem', function(hasItem)
if hasItem then
print('The client can show the option')
end
end, 'water_bottle')For the referenced source, the client wrapper returns a boolean directly:
-- client.lua
local QBCore = exports['qb-core']:GetCoreObject()
local hasItem = QBCore.Functions.HasItem('water_bottle', 1)
if hasItem then
print('The client can show the option')
endThe server wrapper has an additional player source argument:
-- server.lua: inside an already authorized operation for playerSource
local hasItem = QBCore.Functions.HasItem(playerSource, 'water_bottle', 1)The underlying exports likewise differ: client HasItem(items, amount) versus server HasItem(source, items, amount). Do not pass a server ID to the client signature. Keep the server check even when the client already checked visibility. To consume an item, check the result of RemoveItem; HasItem alone neither reserves nor removes it. See the complete usable-item resource.
Replace an old stash caller without exposing every stash
Older resources may call inventory:server:OpenInventory and supply a stash identifier or capacity from the client. Do not assume that legacy event exists in your target version or publish an unrestricted compatibility event to recreate it.
At dc3d07fc, the documented server export is OpenInventory(source, identifier, data). Move the operation into your own server handler, with a server-owned identifier and capacity. In an existing custom resource with client and server files, replace the client call with:
-- client.lua: request only; no arbitrary stash name, slots or weight
TriggerServerEvent('docs_stash:server:open')Use this corresponding server handler. Adapt the sample counter coordinates and authorized job to your server:
local QBCore = exports['qb-core']:GetCoreObject()
local counter = vector3(441.2, -981.9, 30.7)
local nextOpen = {}
RegisterNetEvent('docs_stash:server:open', function()
local src = source
local now = os.time()
if (nextOpen[src] or 0) > now then return end
nextOpen[src] = now + 2
local player = QBCore.Functions.GetPlayer(src)
if not player then return end
local job = player.PlayerData.job
if not job or job.name ~= 'police' or not job.onduty then return end
local ped = GetPlayerPed(src)
if ped == 0 or not DoesEntityExist(ped) then return end
if GetPlayerRoutingBucket(src) ~= 0 then return end
if #(GetEntityCoords(ped) - counter) > 3.0 then return end
exports['qb-inventory']:OpenInventory(src, 'docs_police_training', {
label = 'Training stash',
maxweight = 40000,
slots = 20
})
end)
AddEventHandler('playerDropped', function()
nextOpen[source] = nil
end)Declare qb-core and qb-inventory as dependencies and load server.lua/client.lua in your manifest. This uses OneSync position/bucket checks. It is an original integration example, not a drop-in replacement for a private house or evidence locker: those also require their own ownership/access rules.
Separate player inventory from non-player storage
In the referenced implementation, LoadInventory reads players.inventory, while identifier-keyed non-player storage uses inventories. playerskins is appearance data, not inventory.
The referenced migrate.sql performs an INSERT ... SELECT ... UNION ALL from gloveboxitems, stashitems and trunkitems. It prefixes glovebox identifiers with glovebox- and trunks with trunk-; stash identifiers come from the old stash column. It is not an idempotent migration runner.
Before using that migration on a restored staging database:
- Confirm all required old tables exist and inspect the target
qb-inventory.sql. - Check whether any target identifiers already exist or collide with the incoming rows.
- Record counts and sample contents for each storage type, not just a combined total.
- Apply the reviewed migration once to the staging copy; investigate duplicate-key or missing-table errors rather than suppressing them.
- Open a known stash, trunk and glovebox, change one test item, save/reconnect and compare the result.
Retain legacy tables and backups through the recovery window. A README snippet and a schema file can differ: use the target commit's actual SQL and implementation when choosing column definitions. Never paste a guessed CREATE TABLE from a different inventory fork.
Missing shared items and the UI are different problems
The source loader skips saved items whose names no longer resolve in QBCore.Shared.Items and logs their names. Fix registration before another save turns an incomplete in-memory inventory into a persisted one. Work from a backup if data has already been saved without those items.
For the UI, inspect the actual ui_page and files declared by your installed manifest, then the failed asset or callback in NUI DevTools. Compare your saved FiveM keybinding with the configured default. Read LocalPlayer.state.inv_busy in a temporary diagnostic; find the resource that set it and confirm its close/cancel path instead of clearing it continuously. See NUI callback diagnostics.
Manual acceptance matrix
| Test | Expected evidence |
|---|---|
| Add/remove/use | Correct amount and metadata; rejected removal gives no effect |
| Transfer | One sender decrement and one receiver increment, including capacity rejection |
| Stash/trunk/glovebox | Existing contents retained under the intended identifier |
| Shop | Server-owned price and quantity; no purchase granted after a failure |
| Two players open the same stash | Resource's in-use rules are respected |
| Reconnect and coordinated restart | Saved state matches the previous completed operation |
| Wrong job, remote location or malformed request | No unauthorized access |
Rollback
Restore the previously working caller/core/inventory commits together. If a schema or storage migration was applied, restore the matching database snapshot or use a separately reviewed reverse migration. Do not combine old code with a new schema merely because the server starts. Plan how to preserve legitimate writes made after deployment; reverting files does not roll back player transactions.
Sources
- Inventory server APIs and persistence, dc3d07fc.
- Inventory client HasItem, dc3d07fc.
- Inventory migration and target schema.
- Core client wrappers and server wrappers.
- Cfx.re HasItem discussion: a historical symptom, not authority for every current fork.
Found an issue in this guide?
Send the page URL, the affected example, and a source or reproduction to the site maintainer. For a server or resource problem, use the support guide.
oxmysql errors
Diagnose missing oxmysql resources, connection failures and SQL schema errors in QBCore. Verify the release package, startup order and a read-only query.
No such export
Diagnose QBCore missing exports by provider, startup failure, client/server side and API version. Fix GetCoreObject and inventory mismatches safely.