Troubleshooting
Troubleshooting
Start here
invdoctor
It checks the install end to end and prints each problem with the command that fixes it. Most of this page is things invdoctor will simply tell you.
It starts, but the OLD inventory is still the one that opens
You see aty_inventory in the loading screen, then press your inventory key in game and the previous inventory appears — on Qbox, F2 opening the stock Qbox inventory is the usual shape of this.
Nothing is wrong with this resource. The old one is still running, and it is still the resource answering to the name every other script calls.
Scripts address an inventory by resource name, so taking over from one means taking over its name: stop the original and start the matching proxy from compat/ in its place. On Qbox the original is ox_inventory and it ships with the framework, so it is there whether or not you installed it.
invdoctor
says which of the two you have. A correct install prints "ox_inventory is this resource wearing that name"; a wrong one prints "ox_inventory is running as well as this one" and tells you to stop it.
Also check the console at startup for exists in more than one place — that means both the original folder and the proxy are present, and FiveM picked one for you. Full steps: Compatibility.
The resource will not start
aty_lib missing or starting after it. It is a hard dependency. A folder-wide ensure [aty] does not guarantee order — list aty_lib first.
No MySQL wrapper. One of oxmysql, mysql-async, ghmattimysql must be running.
The panel opens empty
Almost always the framework did not resolve.
invbridge
shows what aty_lib detected. If Framework reads nil on a QBCore server, the bridge started after the inventory.
Items show a placeholder image
Expected for items with no picture. invdoctor reports the count and writes the full list to data/missing-images.txt.
Drop a WebP or PNG named after the item into ui/images/. If the item's definition points at a filename that does not exist, the interface falls back to images/<name>.webp / .png — so naming the file after the item always works, even when the definition is wrong. For items adopted from the framework, point Config.UI.imageFallback at the folder of the inventory they came from.
A gun says "Already full" but it is empty
The weapon has no capacity. Check what it takes and holds:
invitemdef weapon_snspistol
ammo: takes=ammo_pistol capacity=96
takes=nil or capacity=nil on a framework weapon means it was adopted by a version before 1.7.6 — update. A weapon of your own needs ammoType and capacity in its definition.
Money shows twice, or large amounts never appear (Qbox)
Both were fixed in 1.7.5. Qbox keeps cash as its own money item; the mirror keeps that item rather than a second cash copy, and the money item has no stack limit, so a balance above 1000 fits in one slot. If you added a cash item by hand as a workaround, remove it after updating.
invwallet <playerId>
should report backend: qbx.
"Crafting is broken"
Usually it is not. Two candidates, in order:
The wrong item. metalscrap labelled "Metal Scrap" and scrap labelled "Scrap Metal" are different items that read identically at a glance. invdoctor lists confusable label pairs.
The pair already belongs to another recipe. invrecipes shows which.
A stash or crate has a marker but cannot be opened
The key only opens a point from inside its reach — 1.2 m for a stash or shop (Config.Marker), Config.OpenRadius for a crate — which is where the label names the key ([F2]). A point whose groups leave the player out does not open for them either.
Config.Target.enabled is false by default, as in ox_inventory, and then the key is the only way in. With it on, invtarget <playerId> asks that player's client whether a target script is live and how many zones this resource registered there. If targeting works but the key does not, or the reverse, Config.Target (enabled, keepKey) is the first thing to check.
Weight looks wrong
invcheck <inventoryId>
invweight <playerId>
invcheck prints what the server holds and weighs; invweight reports what the player's client thinks they carry, and the move rate that costs. A mismatch between those two weights is the bug; a number you disagree with but that matches on both sides is a config question.
Remember bags: a backpack weighs its own mass plus everything inside it.
Encumbrance does nothing
The game resets the move rate every frame. If a build applies it less often than that, the setting looks right and does nothing. invweight shows whether the rate is actually held on the ped.
An open bag stays open after it leaves you
Fixed in current builds — panels close on commit, for everyone. If you see it, you are on an older build.
A framework item does nothing, or its script errors
Your bandage, your coffee, your job script's item: the player uses it and nothing happens, and the console shows
SCRIPT ERROR: Execution of function reference in script host failed:
> ref (@some-resource/server/main.lua:463)
with no reason given. Ask who runs the item and whether the framework's side is alive:
invroute bandage
invqbmethods 1
invqbcall 1 bandage
invroute names the owner. invqbmethods lists the player methods a qb script finds and calls the ones that answer — anything reported as a dead reference belongs to an older instance of this resource, which is fixed by restarting it again (and was a real bug up to 1.7.2: a restart left those references dead until the player relogged). invqbcall calls the framework's own handler for that item and says whether it survived.
Two resources own one command
FiveM lets a later resource take a command name from an earlier one, silently, and invdoctor does not check for it. This resource steps aside for the one it knows about: giveitem is registered only when qb-inventory is not running, and the console says which way it went at start. After installing anything new that adds console commands, check the ones you rely on still answer.
Something moved that should not have
invtrace <serial> one unit's whole life
invaudit full duplicates, ghosts, orphaned bags
invrollback <tx_id> confirm reverse one transaction
The ledger is the point. If an item exists that should not, the rows that created it are there to read.
Proving a bug
invstress
runs the dupe patterns — a resent request, rapid moves of one slot, two actors racing over one container — and checks nothing was created or destroyed. A last line ending in anything other than CONSERVED is a genuine defect, and the pattern that leaked is marked LEAK above it — include that output in a report.
invchecklist
walks through 24 sections of manual tests, keeping state between runs.