Documentation
Fixes for the most common FiveM Trucker Job problems: renamed folder, blank panel, job and level refusals, hitching, hand-loading, unloading, failed payments, black money, leaderboards and the shop, plus every error key.
What goes wrong most often, what it actually means, and what to do about it. Most of these are configuration, not faults — and the script says in the console exactly what it could not do. With Config.Debug = true it also explains every step of a run, in the server console and in F8.
The folder is not called qs-truckjob. Rename it back exactly — no suffix, no capitals, no version number — and restart the server.
The interface ships compiled in web/build/. If that folder is missing or half-copied the panel never appears — re-copy the whole resource. If pressing E does nothing, stand within 3 metres of the dispatcher, and check Config.Target: with it on the key is not used, and the option comes from the target script set in Config.TargetScript, which has to be running.
The blip only shows to players who can take a contract — with Config.RequireJob = true, give yourself the job first. A missing dispatcher means the model in Config.StartJob.ped never loaded; the F8 console says Ped model '…' never loaded.
The resource's files are incomplete, or the server is still holding an old copy of its file list. Re-copy the whole resource, then run refresh followed by ensure qs-truckjob in the server console. Until it loads, hand-loaded contracts fall back to preloaded runs.
The leaderboard joins its table to your framework's players table, and the two use different collations — MariaDB 11.4 changed the default. The script aligns them on start; if it cannot, the console prints could not align … Run by hand: followed by the exact ALTER TABLE statement. Run it against your database and restart.
Your ESX database has no jobs or job_grades table in the usual shape. The job's own tables are unaffected; add the job by hand from [sql]/qs-Truck.sql or through your own job tooling.
Your job is not in Config.TruckDriverJob. Hand out the job with /setjob <id> truck_driver 0, add your own job's name to that list, or set Config.RequireJob = false. On QBCore and Qbox the job also has to exist in shared/jobs.lua. The same message appears when Config.TrailerLocations or Config.DeliveryLocations is empty.
levelRequired on that contract or rig is above the driver's level. Locked rigs are shown dimmed on purpose, so drivers can see what the next levels unlock; the level is checked again on the server, so it cannot be skipped.
Every slot in Config.VehicleSpawnCoords has a vehicle standing on it. Clear the yard, or add more slots so several drivers can start at once. It is also what a driver sees when the truck could not be spawned at all — check the model names in Config.Vehicles; the F8 console names the model that failed.
The key script started after Trucker Job, so it was not detected — move it above ensure qs-truckjob. A key script that is not in the supported list needs its own calls in client/vehiclekeys/none.lua — see Integrations.
The hitch is checked against where the driver is: you have to be at the trailer bay on the GPS. If the trailer was dragged out of the bay before it coupled, the server answers Hitch up at the trailer bay marked on your GPS — bring the rig back to the amber ring. It is asked again every few seconds while you stay hitched.
The pile is built as you approach the dock on the GPS, and the prompt only appears on foot, a few metres from the boxes. Bring the trailer over to the boxes first means the trailer is more than 25 metres from the pile. If Config.ManualCargo.sites is empty the server hands out a preloaded run instead and says so in the console.
You are loading at a different dock from the one the server has the run on. Follow the GPS: the docks are visited in a fixed order, and each one has to be cleared before the next. The box goes back to the pile, so nothing is lost.
Only a box with nothing on top of it can be taken, the way a person would unstack it. Point at the top of the pile — a box lights up when it can be grabbed.
On a hand-loaded run with Config.UnloadAtDelivery = true, the freight has to come off at the drop-off before the trailer counts. Walk to the trailer, press E and unload it, then drive the empty trailer back to its bay.
A hand-loaded run needs a flatbed at about the deck height of trflat in Config.CargoTrailerModels. A closed or much taller trailer cannot hold the load properly. If that list is empty, the console says Config.CargoTrailerModels is empty.
The server no longer had the run: the resource restarted, an admin or another script cancelled it, or the driver changed job. Runs live in the server's memory, so a restart always ends them — the truck and the trailer are cleared away and nothing is paid.
The framework refused the money. On ESX the account does not exist — almost always black_money on a stolen-cargo run. On QBCore and Qbox the black_money item is missing from your inventory, or the driver's bag was full. With qs-job-management running, Job Management refused the payout. The experience is still given — only the money failed to move.
The police were alerted when the trailer was handed over. A reported run pays no money and no experience, by design. The chance falls with every level up to Config.MaxBonusLevel — see Usage.
The card shows a rate per 100 metres. A run is paid for its whole route — every dock and the drive back included on a hand-loaded run — plus every box, times the rig and the kind of load. The tracker shows the exact amount from the moment the run starts.
That driver's identifier has no character left in users (ESX) or players (QBCore) — usually a deleted character. Drivers with no experience in a ranking are left out of it entirely.
A winner who is offline at the reset is paid in cash the next time they log in. A server that was down at midnight, or on the first of the month, runs the missed reset as soon as it starts again.
An item in Config.Shop is not registered in your inventory, and the server console names it too. Add it — see Installation — or take it out of the shop. Nothing is charged for it.
The bag had no room for part of the order. Only what actually arrived is charged.
Each one hides when its feature is off: Config.Shop.Enabled (off by default), Config.EnableLeaderboard and Config.EnableGuide.
The server answers a refusal with a translation key, so the same failure reads in your server's language. The ones you are most likely to meet:
Key | Means |
|---|---|
| The player has no allowed job — or the contract, the trailer bays or the drop-offs could not be found. |
| A run is already in progress. |
| The contract needs a higher level. |
| The rig needs a higher level. |
| No free spawn slot, or the truck could not be spawned. |
| The trailer was hitched away from its bay. |
| The trailer is more than 25 m from the pile. |
| Boxes are moved on foot, not from the cab. |
| The box was moved at a dock the run is not collecting from. |
| The load has to come off before the trailer is handed over. |
| The stolen-cargo offer was no longer valid when it was accepted. The run carries on unchanged. |
| The framework, or Job Management, refused the money. |
| A shop item is not registered in the inventory. |
| No room for part of a purchase. |
Still stuck? Open a ticket and include your framework and its version, every
qs-truckjobline from the server console, and what the F8 console shows withConfig.Debug = truewhile you reproduce the problem.
