4 min read
qb-inventory
qb-inventory is QBCore's inventory resource. It owns player/item storage behavior, registered
inventories and shops, drops, UI opening, persistence helpers, inventory hooks/listeners and the
player item methods it attaches while the resource is running.
Use the resource exports instead of directly mutating inventory tables.
Conceptual diagram; verify the behavior against your installed resource version.
For opening failures, use inventory diagnostics. Before replacing this resource, read the ox_inventory bridge and migration checks.
Download and install qb-inventory
For QBCore inventory, use the upstream qb-inventory repository.
The qb-core download is the framework core, not the inventory resource. Setting up a whole server?
See Download QBCore and the txAdmin recipe before installing individual resources.
The upstream README lists
qb-core and qb-smallresources for logging as dependencies. Check the
manifest, configuration and
README at your selected commit as well; forks can have different requirements.
- Back up your resource files and database. Work on a staging copy first.
- Download or clone the upstream repository, record its commit, and keep the resource folder named
qb-inventoryinside your[qb]group. - For a fresh install, review and import the repository's
qb-inventory.sqlinto the intended server database. Do not import it blindly over an existing inventory installation. - For an upgrade, follow the SQL and migration instructions for your existing and target revisions. Validate migrated player inventories and stashes before removing any old tables; keep a restorable backup.
- Start the dependencies before inventory and any resources consuming its exports. Check the first server-console error before testing the UI.
- Test item use, capacity limits, shops, stashes, reconnects and persistence after a server restart.
For UI-only changes, use the qb-inventory reskin guide. For failed opens or item operations, jump to troubleshooting or inventory update troubleshooting.
Start order
A normal QBCore setup starts the core before inventory consumers:
ensure qb-core
ensure [qb]When debugging, confirm qb-inventory itself is started before a custom resource calls its exports.
See Resource load order.
Current server exports
The current server/functions.lua exposes inventory operations including:
OpenInventoryOpenInventoryByIdCreateInventoryGetInventoryRemoveInventoryAddItemRemoveItemCanAddItemCreateShopOpenShopClearStash
The exact source file contains additional helpers. Pin your integration to the revision you deploy.
Add an item
local added = exports['qb-inventory']:AddItem(
source,
'water_bottle',
1,
false,
false,
'my-resource:reward'
)
if not added then
-- Handle full/invalid inventory.
endRemove an item
local removed = exports['qb-inventory']:RemoveItem(
source,
'water_bottle',
1,
false,
'my-resource:consume'
)Check capacity before adding
local canAdd, reason = exports['qb-inventory']:CanAddItem(source, 'water_bottle', 1)
if not canAdd then
print(reason) -- for example weight or slots
return
endCreate and open a custom inventory
exports['qb-inventory']:CreateInventory('evidence-123', {
label = 'Evidence 123',
maxweight = 100000,
slots = 30
})
exports['qb-inventory']:OpenInventory(source, 'evidence-123')Treat identifiers as server-owned values when access matters. Do not let a client choose an arbitrary stash name and then open it without authorization.
Player methods
Current qb-inventory adds item methods to connected QBCore player objects, including AddItem,
RemoveItem, item lookup, ClearInventory and SetInventory.
That compatibility layer comes from qb-inventory, not from the permanent qb-core API. Direct inventory exports make ownership clearer in new integrations.
Inventory busy state
The resource uses the player state bag inv_busy to prevent conflicting opens/moves.
Before building a custom UI that manipulates inventory, understand when the resource sets or clears that state rather than introducing a second independent lock.
Shops
Register server-defined shops through the current inventory API instead of sending authoritative prices from the client.
A shop definition should be built on the server from trusted config, then opened for the player through the inventory's shop path.
For QBCore's dedicated shop resource, see qb-shops.
Hooks and listeners
Current qb-inventory exposes server-side AddHook and AddListener exports for operations such as
opening an inventory, moving items, and adding or removing them. Hooks can reject a supported
operation before it completes; listeners observe completed operations.
See the source-verified hooks, payloads and event reference for runnable registration examples, event names and differences between hooks, listeners and UI transport events. Always authorize inventory access in your server resource; a hook is not a substitute for the caller's own permission checks.
Persistence
Player inventory is synchronized with the QBCore player object and persisted by the inventory/core integration. Non-player inventories are handled by qb-inventory's own storage paths.
Do not create random tables such as player_items, stashitems or trunkitems because an old
tutorial used them. Import only SQL shipped by the repository/recipe version you deploy.
Security pattern
For a reward:
RegisterNetEvent('myjob:server:claimReward', function(jobId)
local src = source
local Player = exports['qb-core']:GetPlayer(src)
if not Player then return end
-- Validate jobId, player state, proximity, cooldown and ownership server-side.
local reward = resolveTrustedReward(jobId)
if not reward then return end
exports['qb-inventory']:AddItem(src, reward.name, reward.amount, false, false, 'myjob:reward')
end)The client may request an action; it should not decide item names, quantities, prices or reward eligibility.
Troubleshooting
| Symptom | Check |
|---|---|
| Inventory will not open | Resource state, first console error, inv_busy, and caller API version. |
AddItem returns false | Item exists in shared items, available slots/weight, correct identifier. |
| Item shows no image | Item definition image name and files in the inventory UI assets. |
| A stash can be opened by anyone | Authorization is missing in the calling server resource. |
| Old export/event is missing | Compare your code against current server/functions.lua and migration notes. |
See Inventory update troubleshooting and the events/functions reference.
If you replace the default inventory instead of patching it, compare inventory scripts on RPScripts by declared QBCore version, dependencies and data migration path. RPScripts and qbcore.net are operated by the same owner.
Sources
- qb-inventory repository
- Current server functions
- Current server main
- Official qb-inventory documentation
Source references and literal export names rechecked against commit dc3d07fc on 2026-10-13. This is static evidence, not FXServer or database acceptance.
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.
qb-crafting
Source-verified qb-crafting setup: recipe format, item and attachment benches, XP progression, target interaction and security limitations.
Inventory events & hooks
Use the real qb-inventory hooks, listeners, server exports, and UI events with correct payloads and secure integration examples.
