Troubleshooting#

Fixes for the problems people actually hit, roughly in the order they show up.

"UI has not been built" on start#

web/build is missing. The release zip ships it prebuilt — download the zip again and copy the whole ox_inventory folder.

The resource does not start: ox_lib or oxmysql version#

Koja Inventory needs oxmysql 2.7.3+ and ox_lib 3.36.4+, started before it. Update them and check the order in server.cfg.

Scripts calling exports.ox_inventory error out#

The folder is not named ox_inventory. Exports are registered under the folder name. Rename the folder.

"ox_target is not loaded - it should start before ox_inventory"#

You set inventory:target true but ox_target starts later (or not at all). Move ensure ox_target above ensure ox_inventory.

"You do not have permission to open the inventory admin panel"#

• Your player does not have the group.admin ace (admin.superAce). Check add_principal and add_ace group.admin group.admin allow in server.cfg.
• Or add yourself as staff: put your identifier in data/koja/staff.lua (['license:...'] = 'owner') and restart.
• A staff member sees only the pages their role allows. Check the role on the Permissions page.

Slots show "Need a backpack"#

That is the slot layout: only baseSlots (25) are always unlocked, the rest up to inventory:slots needs a worn backpack. Raise baseSlots in data/koja/core.lua or wear a backpack. Locked slots stay locked when the Backpacks addon is off.

"Empty the backpack slots first."#

You are taking off (or swapping) a backpack while its extra slots still hold items. Move those items into the base slots first.

Clothing items have no images#

• No appearance resource with getClothingImage runs, or its name does not match clothing.imageResource (default illenium-appearance). Change it in data/koja/core.lua or on the admin Clothing page.
• The appearance resource has no thumbnail for that piece yet. With Koja Appearance, capture it in its Capture panel.
• Without images the UI shows web/images/clothing_<slot>.png or an icon.

Clothes change back or come back as items after using a skin menu#

That is clothing.externalAppearance: an appearance saved by illenium-appearance / fivem-appearance wins over the worn items, and removed pieces go back to the inventory. Set it to false if your clothing shop should not touch the items.

"This piece of clothing doesn't fit your character."#

The clothing item was made for the other freemode gender.

The ped preview is missing#

• The player turned off Clothing inventory in Settings.
• You sit in a vehicle — the ped preview is not shown there.
• With Camera on character off, the ped is drawn inside the UI instead of moving the camera.

No "press E" prompt at shops#

• The shop is handled by ox_target (inventory:target true and the shop has targets) — the prompt is off for those unless the shop sets interaction = true.
• The 3D shop interaction addon is off, or shop.interaction.enabled = false in data/koja/interact.lua.
• If the 3D card cannot load, a plain text prompt is drawn instead. Set shop.dui.enabled = false to always use the text prompt.

Card payment fails#

Card uses the framework bank account. Check that inventory:framework matches your framework and that the shop's paymentMethods contains card.

Data file changes do nothing#

The admin panel wins. An item, shop, stash, bench, rarity or setting saved in the panel is stored in the database and overrides data/. Use Restore file version (benches), delete the saved shop / stash, or remove the row from the koja_inv_* table.

Players never get the trade request#

• The players are further apart than trade.distance (3 m).
• Y / N only work while the inventory is closed; with it open, the request is a card in the UI.
• The Trading addon is off.

An item cannot be thrown#

• The item has throwable = false, or throw.anyItem = false and the item has no throwable = true.
• Weapons: grenades and other thrown weapons are blocked (denyProjectiles), and so is everything in throw.weapons.deny. You cannot throw while aiming, shooting, reloading, in a vehicle or with the inventory open.

Dumpsters and trunks are always empty#

• inventory:randomloot is false.
• The loot tables on World containers are empty.
• Dumpsters already searched keep their contents until the server restarts.

Parts of the UI are in English#

Only en.json and pl.json contain every Koja string. Translate the rest on the admin Locales page or in locales/<lang>.json — see Translations.

Nobody can open any inventory#

Someone turned on Emergency inventory lock on the Security page. Turn it off there; it is also off after a restart.