ESX to Qbox Migration: The Full Procedure for FiveM Servers

Why this is a project and not a script

ESX Legacy and Qbox are different lineages. Qbox descends from QBCore, not from ESX, so unlike a QBCore to Qbox move there is no shared ancestry to lean on: player identity, money storage, inventory, and vehicle ownership are all shaped differently, and every resource written against ESX internals has to be replaced or bridged. Community migration scripts exist and some are good, but each one encodes assumptions about a specific schema at a specific version, and player data is the one thing you cannot restore from a forum post. Treat any such tool as a starting point you verify, not a product you run.

The good news is that the shape of the work is fixed and known. Everything below is the same four-domain mapping and the same resource audit whichever tools you use to do it, and the reconciliation step at the end tells you honestly whether it worked. Facts about both frameworks are as of September 2026; verify current table shapes against each project's own documentation before writing a single query.

Step one: the resource audit decides the timeline

Before touching data, list every resource on the server and put it in one of three groups. Framework-agnostic resources — maps, vehicles, many UI utilities — move as-is. Bridge-built resources talk to the framework through an adapter module and move with a bridge config change. ESX-coupled resources call ESX internals directly: `ESX.GetPlayerFromId`, account add and remove calls, es_extended events, ESX-shaped job tables. Those are the ones that must be replaced with a Qbox-native or bridge-built equivalent, or rewritten.

Searching each resource's server files for `ESX` is a crude but effective first pass on open resources. Escrowed resources you cannot search; for those, the seller's listing either names a bridge and a Qbox test matrix or it does not, and an escrowed, ESX-only resource is one you are replacing. Count the third group. That number, not the framework, is your timeline — and it is the reason to prefer bridge-built resources at purchase time (/guides/fivem-framework-lock-in).

Step two: a clean Qbox server on staging

Do not migrate in place. Stand up a second server — a staging box with the same FXServer artifact version production will run — and deploy Qbox onto it cleanly, with the ox stack it expects: ox_lib, oxmysql, ox_inventory, ox_target. txAdmin's recipe deployer is the fastest way to get there. Point it at a copy of the production database, never the live one, and give it a separate keymaster key so nothing you do on staging touches production grants.

This is also where your resource list gets rebuilt in the right order: framework, then database layer, then shared libraries, then inventory, then everything that depends on them (/guides/fivem-server-start-order). Migrating and re-ordering at the same time sounds like double work; it is actually how you avoid discovering a load-order problem on cutover night and blaming the migration for it.

Step three: the four data domains

Characters first, because everything else keys off them. ESX identifies a player by a license-style identifier and stores character rows with that identifier; the QB lineage identifies each character by a citizen ID and stores character info as structured data on a players row. The mapping is one ESX character to one Qbox player row with a newly generated citizen ID, plus a lookup table you keep so the other three domains can find the new key. Verify the row count matches before moving on.

Money second. ESX keeps balances in accounts (cash, bank, and any you added); Qbox keeps them in money fields on the player. The conversion is mechanical, but the check is not optional: sum every account across every player before, sum every money field after, and require equality. A migration that loses or creates a dollar has a bug you have not found yet, and an economy is the one place a small error compounds.

Inventory third, and this is the domain most likely to hurt. If you were already running ox_inventory on ESX, the items table travels with a re-key to the new citizen IDs. If you were on the ESX default inventory or another system, item definitions, metadata, stashes, and shops all need re-creation in ox_inventory's model, and some items will simply not have an equivalent. Decide deliberately what happens to those rather than letting the script decide. Vehicles fourth: ESX's owned-vehicles rows map to Qbox's player-vehicles rows with the owner re-keyed and the vehicle properties carried across; garages and impound state depend on which garage script you run, which is one of the coupled resources you audited in step one.

• Characters: one ESX character → one Qbox player row + new citizen ID; keep the old-to-new lookup.
• Money: sum all accounts before, sum all money fields after, require equality.
• Inventory: items re-keyed if already on ox_inventory; rebuilt if not. Decide what happens to items with no equivalent.
• Vehicles: owner re-keyed, properties carried across; garage and impound state depend on the garage resource.

Step four: replace, bridge, and test each coupled resource alone

With data on staging, work through the ESX-coupled list one resource at a time: install the replacement, start it, exercise its feature, and read the console before adding the next. Testing resources one at a time is slower than starting everything and seeing what breaks, and it is the only way to attribute an error to the resource that caused it. When a replacement touches money or items — a banking, jobs, or shop script — re-run the money reconciliation after testing it, because a resource that mints or loses money in a test will do the same to players.

Restart safety is the test people skip. Restart the staging server after the data is in and the resources are up, and confirm characters, balances, inventories, and vehicles are still there and still correct. A migration that looks right until the first restart is the most common failure shape, and it is cheap to find on staging and expensive to find at 3am (/guides/fivem-restart-safety).

Cutover: reconcile, freeze, switch, keep the old server

Schedule a window, announce it, and freeze the ESX server — no logins — so the data you migrate is the data players last saw. Take a fresh backup, run the migration against a fresh copy, run the reconciliation queries one more time, and bring the Qbox server up on the production key. Keep the ESX server intact and startable until the Qbox server has survived a restart cycle and a busy session with real players; if the numbers stop reconciling in the first week, you want a way back that does not involve a restore from before the migration.

Then write down what you learned. Which resources were coupled, which replacements worked, what the item-mapping decisions were — because the next migration a server does is usually the next framework, and the audit you just did is the first half of it.