QBCore Frameworkqbcore.netCommunity docs
On this page

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.

Inventory client requests and server synchronization

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.

ObservationNext checkEvidence of a fix
No response to the inventory keySaved keybinding, configured command and whether the client resource loadedThe intended command reaches the installed handler
Cursor appears but inventory is blankManifest UI files, built assets, first NUI error and failed requestsUI loads and its open/close callbacks finish
Inventory refuses to open after an actionRead inv_busy; identify the operation that set it and its cancellation/cleanup pathAction completes or cancels, then normal opening works
Inventory only fails before character selectionPlayer-ready lifecycle and first character-loading failureNormal opening after a completed login, without forcing readiness
Missing LoadInventory or OpenInventory exportProvider name, startup error, execution side and installed APIMatching caller/provider works on clean startup and reconnect
Two inventory interfaces or repeated focus problemsCompeting resources and duplicate key/command handlersOne 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 --stat

A 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

SymptomFirst checkDo not do first
QBCore:HasItem is deprecatedFind the caller of the old callback and its execution sideGlobally replace every occurrence of HasItem
Missing AddItem, OpenInventory or another exportIs the provider started, and does that exact commit export it on this side?Rename the call until the error disappears
One new item is absentExact shared key/name and valid items.lua syntaxRecreate the inventory database
Inventory opens without the expected iconimage filename, capitalization and asset requestTreat the PNG as the item registration
Personal inventory works, stashes are emptyOld/new storage tables, identifiers and migration historyRun migrate.sql repeatedly
Key does nothing or UI remains stuckF8/NUI error, keybinding, inv_busy, focus and competing inventory scriptsForce inv_busy = false for all players
Items vanish after reconnectMissing shared definitions, save errors and persisted JSONDelete 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')
end

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

  1. Confirm all required old tables exist and inspect the target qb-inventory.sql.
  2. Check whether any target identifiers already exist or collide with the incoming rows.
  3. Record counts and sample contents for each storage type, not just a combined total.
  4. Apply the reviewed migration once to the staging copy; investigate duplicate-key or missing-table errors rather than suppressing them.
  5. 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

TestExpected evidence
Add/remove/useCorrect amount and metadata; rejected removal gives no effect
TransferOne sender decrement and one receiver increment, including capacity rejection
Stash/trunk/gloveboxExisting contents retained under the intended identifier
ShopServer-owned price and quantity; no purchase granted after a failure
Two players open the same stashResource's in-use rules are respected
Reconnect and coordinated restartSaved state matches the previous completed operation
Wrong job, remote location or malformed requestNo 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

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.

On this page