How to Install QBCore Scripts

The generic install steps — unzip, ensure, restart — get a QBCore script running. What they do not do is register its items, its jobs or its permissions, and that is where most QBCore installs actually stall. This guide covers the QBCore-specific work that the readme usually assumes you already know.

Start order is not optional

QBCore scripts read a shared core object at start. If qb-core has not started yet, that object does not exist and every script above it fails with attempt to index a nil value (global 'QBCore'). Your server.cfg should read roughly in this order:

• ensure oxmysql — the database layer, before anything that queries
• ensure qb-core — the framework itself
• ensure ox_lib — shared UI and callback library, if your scripts use it
• ensure qb-inventory (or ox_inventory) — whatever holds items
• …then every gameplay resource

The error is misleading because it names the script that failed rather than the framework that was missing, so it sends people to the wrong readme. If a brand new script throws a nil QBCore error, check the order before you check the script.

Adding items to shared/items.lua

Anything a script gives, takes or consumes must exist as an item first. In QBCore that means an entry in qb-core/shared/items.lua, and the key you write there is the name the script will reference in its own config:

['lockpick'] = { name = 'lockpick', label = 'Lockpick', weight = 100, type = 'item', image = 'lockpick.png', unique = false, useable = true, shouldClose = true, description = 'Opens things that are not yours' },

Three fields cause most of the trouble. image must match a real file in your inventory resource's image folder, or the item shows as a blank square. useable must be true for anything the player is meant to click. And unique controls whether the item stacks — get this wrong on a crafting item and players will either lose stacks or duplicate them.

If you run ox_inventory instead of qb-inventory, items live in ox_inventory/data/items.lua in a different format. Scripts that support both will say which one they expect; putting the item in the wrong file produces a script that runs but never finds its own items.

Registering jobs and grades

Job-based scripts check PlayerData.job.name against a string in their config. That job has to exist in qb-core/shared/jobs.lua with matching grades, or the check silently fails and nothing opens. The job name is case-sensitive and must match exactly — mechanic and Mechanic are different jobs to QBCore.

Grades matter for permission gates. A script that restricts a menu to grade 3 and above will do nothing for a player on grade 0, which looks identical to a broken script from the player's side. When testing, set yourself to the highest grade first, confirm the feature works, then test the gate.

Import the SQL before the first start

QBCore scripts that persist anything — owned vehicles, owned property, job data — ship a .sql file. Import it into your database before starting the resource. Starting first produces database errors on the first player interaction rather than at boot, which makes them look like gameplay bugs instead of a missed setup step.

Checking that it actually loaded

After a restart, run ensure again from the console on just that resource and watch the output. A resource that starts clean prints nothing after its name. Any Lua error at start means the script never registered its exports, and every later interaction will fail regardless of your config.

Where to go next

Every ATY script detects QBCore automatically and ships with a QBCore section in its docs. If you are weighing QBCore against ESX before committing, our QBCore vs ESX comparison covers what actually differs in practice. For a worked example, the FiveM Garage Script & Ownable Garages install is documented end to end.

Every ATY script ships with its own setup page in the documentation, and delivery is automatic through Cfx.re Keymaster the moment payment clears. Browse the full catalogue in the store, or open a ticket in our Discord if you get stuck — you talk to the developers who wrote the code.