What goes wrong most often, what it actually means, and what to do about it. Almost every refusal in Hunter Job tells the player why in plain words, and the owner's mistakes — a missing item, a model that never loads, an animal a mission names but the config does not have — are printed in the server console or in F8. Read those first; turn on Config.Debug if you need to see more.
Installation and Startup#
"You have renamed the script!" and the console freezes
The resource folder is not called qs-hunter. It must be — a renamed copy stops the server on purpose. Rename the folder back, fix the ensure line in server.cfg and restart.
The employer does not appear
The NPC is spawned by the framework bridge, so the usual cause is a framework that starts after qs-hunter and was never detected. Move ensure qs-hunter below your core.
If F8 shows Ped model '…' never loaded., Config.StartJob.ped.model has a typo or names an add-on ped that is not streamed.
There is no blip on the map
Correct behaviour for a player without the job: the blip is shown only to players holding a job in Config.HunterJob, and it appears the moment they get it. With Config.RequireJob = false everybody sees it. Check Config.EnableBlip too.
"Illegal mix of collations" and an empty leaderboard
Your database's default collation differs from the one the hunter tables were created with — typical on MariaDB 11.4 and newer. The script aligns its identifier columns on every start and prints aligned N identifier column(s) when it did. If the database user is not allowed to alter tables, it prints the exact ALTER TABLE statement instead — run it by hand and restart.
"Could not verify the database schema" or "Could not register the ESX job rows"
The first means the tables could not be created or checked: oxmysql is not connected, or the database user lacks CREATE and ALTER rights. Fix the connection, or import [sql]/qs-hunter.sql by hand.
The second only matters on ESX: there is no jobs table it could write to. The hunter tables are still fine — add the job with the two inserts at the top of the same SQL file.
Missions and Crews#
"You don't have the hunter job"
The player's job name is not a key in Config.HunterJob. The match is exact — hunter, not Hunter. On QBCore and Qbox the job must also exist in shared/jobs.lua before /setjob will hand it out — see Installation.
The mission will not start
The server checks every member before it starts and names the rule that failed:
One of the members does not have the level required — somebody is below the mission's
levelRequired.One of the members does not have the hunter job — somebody changed job after joining.
One of the members is already on a mission — they must finish or abandon it first.
Only the group leader can do that — a member pressed Start Mission; only the leader can.
An invitation is refused
Message | Means |
|---|---|
The player is too far away | More than |
That player has just been invited, give them a moment | They have an unanswered invitation, or were invited by somebody in the last 10 seconds. |
Slow down, you have just sent an invitation | Less than 1.5 seconds since the leader's last invitation. |
Player is already in the party | They belong to another crew. They leave it first. |
Your group is already full | The crew has |
That player is not online | No player has that server ID. |
Crew tiles show initials instead of faces
A face can only be photographed when that player is close enough to be drawn by your game. Anyone out of range gets their initials, and F8 says why with no mugshot for …. Nothing is broken — stand closer and reopen the panel.
The animals never appear
They spawn at their hunting ground, not near the employer — follow the circle on the map. If the circle is missing too, F8 explains:
Task 7 wants animal 'pig', which is not in Config.Animals.— a mission names an animal the config does not define. Fix the spelling or add the animal.Animal model '…' never loaded.— the ped model inConfig.Animalsis wrong.
Harvesting#
"The animal was not taken down with the appropriate weapon"
It was killed by something other than Config.HunterWeapon — another gun, a melee hit, a car, a fall — and the carcass was removed. Use the rifle, or set Config.HunterWeaponNeeded = false to accept any kill.
"You need a hunting tool" or "You don't have enough level to use hatchet"
Config.RequireToolToHarvestAnimal is on and the player carries neither tool — or only the hatchet, below Config.AxeRequiredLevel. A knife from the shop solves both.
"You are too far from the hunting ground"
The server measures from the animal's coords in Config.Animals, allowing Config.SpawnRadius + Config.HarvestZoneMargin (520 m). An animal that fled further than that cannot be claimed — raise the margin if your grounds are wide.
"Your mission does not ask for this animal" or "You have already harvested your share"
Each member may skin only the animals their mission names, and only as many of each as it asks for. The rest of the crew's counter still needs their own animals — the extra carcass is not worth anything.
"This item does not exist: rat_meat"
The drop is configured but your inventory has no such item. The server console names it each time it happens:
[qs-hunter] rat_meat is configured as a drop but no such item exists in the inventory.The player keeps the experience and the mission progress; only the item is lost. Add the items as shown in Installation and restart the inventory.
"Your inventory is full"
Nothing fitted, so nothing was given and the animal did not count towards the mission. Sell or drop something and skin the next one.
Pressing E over a carcass does nothing
Targeting is on — use the third eye; key prompts are not drawn with
Config.Target = true.The player is not on a mission, or the carcass belongs to a crew mate — each member can only skin the animals their own game spawned.
They pressed again too soon. Harvests are limited to one per animal harvest time.
They are more than 3 m from the body.
Shop and Money#
"This item does not exist: snp_ammo" when buying
The shop sells an item name your inventory does not use. Nothing was charged for that line, and the console says which one:
[qs-hunter] snp_ammo is on sale in the shop but no such item exists in the inventory.Almost always the ammo: on ox_inventory change the Ammo entry of Config.BuyItems to ammo-sniper.
"You don't have enough money" with money in the bank
The shop charges cash. To use the bank instead, change the account in the server bridge — Paying into the bank in Integrations shows the three lines.
The rifle has no ammunition
Only ox_inventory loads the rifle on purchase. Everywhere else, buy the Ammo pack beside it.
Mission pay never reaches the player's cash
qs-job-management is running, so the pay was handed to it — that is where to look. Sales and leaderboard prizes still pay cash.
The mountain lion items have no picture
The icons in the download are meat_mtlion.png and hide_mtlion.png. Point lion_meat and lion_hide at those names in your item list.
Leaderboard#
The leaderboard is empty
Only hunters with experience in that period are listed, so a fresh day or month starts empty. The boards refresh every Config.UpdateLeaderboard minutes — a first harvest shows up within one. If it stays empty after that, look for the collation error above.
A winner says they were not paid
They were offline at the reset. Their prize is banked in qs_hunter_rewards and paid in cash the next time their character loads.
Names show as "Unknown"
The hunter has no matching character row — users with a first name on ESX, players with charinfo on QBCore. Usually a deleted character.
The daily ranking resets at the wrong hour
Resets run at midnight in the server machine's time zone, not the players'. Change the host's time zone to move it.
Message Keys#
Every refusal is a key in config/translations.lua, so it reads in each server's own language. Search for the key to reword it.
Key | Means |
|---|---|
| No hunter job — or, when harvesting, not on a mission. |
| The player, or a crew member, already has a hunt running. |
| A crew member is below the level or without the job. |
| Only the leader may do that · the crew is full. |
| Invitation refused: offline, in another crew, or invited moments ago. |
| The leader is inviting too fast · the player is out of invite range. |
| Killed with the wrong weapon; the carcass is gone. |
| A tool is required and the player has none they may use. |
| Outside the animal's hunting ground plus the margin. |
| The mission does not want that animal · the player's share is done. |
| No room for the item · the inventory has never heard of it. |
| The basket costs more than the player's cash. |
Still stuck? Open a ticket and include the server console from the start of
qs-hunter, the F8 output withConfig.Debug = true, your framework and inventory, and the exact message the player saw.