# 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](/diagrams/inventory.svg)

*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](/docs/troubleshooting/no-such-export). If switching inventory providers, follow the [ox_inventory compatibility checks](/docs/guides/ox-inventory-qbcore) 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.

```bash
# 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

| 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](/docs/troubleshooting/resource-load-order), [keybindings](/docs/guides/keybindings) and [oxmysql](/docs/troubleshooting/oxmysql).

## Fix

### HasItem: match both the API and the execution side

An old client pattern you may find is:

```lua
-- 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:

```lua
-- 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:

```lua
-- 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](/docs/guides/item-use-effect).

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

```lua
-- 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:

```lua
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](/docs/troubleshooting#nui-getparentresourcename).

## 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](https://github.com/qbcore-fivem/qb-inventory/blob/dc3d07fc60139de569df38c5ac178ed4cada4577/server/functions.lua).
- [Inventory client HasItem, dc3d07fc](https://github.com/qbcore-fivem/qb-inventory/blob/dc3d07fc60139de569df38c5ac178ed4cada4577/client/main.lua).
- [Inventory migration](https://github.com/qbcore-fivem/qb-inventory/blob/dc3d07fc60139de569df38c5ac178ed4cada4577/migrate.sql) and [target schema](https://github.com/qbcore-fivem/qb-inventory/blob/dc3d07fc60139de569df38c5ac178ed4cada4577/qb-inventory.sql).
- [Core client wrappers](https://github.com/qbcore-fivem/qb-core/blob/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf/client/functions.lua) and [server wrappers](https://github.com/qbcore-fivem/qb-core/blob/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf/server/functions.lua).
- [Cfx.re HasItem discussion](https://forum.cfx.re/t/script-qb-inventory-qbcore-hasitem-is-deprecated-please-use-qbcore-functions-hasitem-it-can-be-used-on-both-server-and-client-side-and-uses-the-same-arguments/5060277): a historical symptom, not authority for every current fork.
