What goes wrong most often, what it actually means, and what to do about it. When something is not working and you cannot tell why, set Config.Debug = true, restart, and read the server console and the client console (F8): the job explains every step it takes and shows how far it got. Turn it off again on a live server — it prints a lot.
Installation and Access#
The console freezes after "You have renamed the script!"
The resource folder is not called qs-lifeguard. The freeze is deliberate. Stop the server, give the folder its name back, update server.cfg to ensure qs-lifeguard and start again.
No captains, blips or prompt at the stations
The stations only appear for players who may work them. In order of likelihood:
The player's job is not in
Config.LifeguardJobwhileConfig.RequireJobis on.The framework starts after Lifeguard Job, so none was detected. Move it above
ensure qs-lifeguard.Config.Target = truewithout ox_target running: the captains are there but have no option. Start ox_target first, or turn the setting off.The player has just switched character — the stations are rebuilt about two seconds later.
"You are not a lifeguard."
The job the player holds is not listed in Config.LifeguardJob. On QBCore and Qbox, also check the job exists in shared/jobs.lua with exactly that name. The same message appears when a call-out is finished by somebody who has changed job since it started — they are not paid for it.
"You are not allowed to do that" on /lifeguardadmin
The player lacks the ACE command.lifeguard. Grant it to their group and make sure they are in that group:
add_ace group.admin command.lifeguard allow
add_principal identifier.fivem:1234567 group.adminAlso check that Config.AdminPanel.Enabled is not false, and that the ACE there was not renamed.
The lifeguard job does not exist on ESX
The job is written to the database on the first start, but ESX reads its jobs when it starts — restart the server once afterwards. If the console printed Could not register the ESX job rows, your database has no jobs table the job could write to: import qs-Lifeguard.sql by hand.
I edited config.lua and nothing changed
Two possible reasons. Either the resource has not been restarted since — config files are read at start — or that setting was saved from the settings panel, which wins over the file. Open /lifeguardadmin, find the setting (it is marked as changed from the panel), press the arrow to give it back to the file and restart.
The uniform does not go on, or is wrong
The uniform needs Config.Clothing = true and, on ESX, esx_skin and skinchanger; on QBCore, qb-clothing. With another clothing resource, point ApplyJobClothes and RemoveJobClothes in config/clothing.lua at it, or turn the uniform off. The pieces themselves are the numbers in that same file.
Patrols and Call-outs#
Checkpoints never raise a call-out
Some checkpoints are meant to be quiet — at level 1 only 40% raise anything. If none ever do:
On the water at low levels there is little to find: every simple call-out happens on the sand.
The shift must have been started from a station. A player who simply drives to the checkpoints is not on duty.
Arriving at the same stretch of beach again within a minute does not count — ride on to the next checkpoint.
After a call-out ran out of time or was abandoned, the next one can take up to a minute to turn up.
Solo call-outs pause while a cooperative rescue is running.
"Incident abandoned."
The call-out ran out of time. Each one has its own limit — the timeout field in config/incidents.lua, in seconds — which you can raise from the settings panel's Call-outs page.
A call-out was finished but nothing was paid
The server pays only when every one of these is true:
the player still holds the lifeguard job;
it was finished within its time limit;
the player is still on or around the beach;
it was a call-out the server issued to that player — one that was not abandoned or already paid.
If you moved stations or routes far from the beach, keep them together: pay is only given within a few hundred metres of the configured checkpoints and stations.
"Cannot change vehicle during an active incident."
Vehicles cannot be swapped or stored while a call-out is open. Finish it first, or use End Shift, which abandons it.
"You have not unlocked this vehicle yet."
The vehicle's minLevel is above the player's level. Jetskis start at level 2 by default, so a brand-new lifeguard has only the land patrol.
"You must be on a vehicle to rescue them."
The Exhausted Swimmer, and the surfers of the Missing Surfer rescue, climb on behind you — ride up on your jetski before using the option. The passengers of the Sinking Vessel are the opposite: you rescue them in the water, off the jetski.
The vehicle does not appear
Look in F8 for could not load vehicle model: the spawn name in Config.VehicleTypes is wrong, or an addon vehicle is not streamed. For a land vehicle, also check the station's land spawn point is clear ground a few metres from the captain.
The lifeguard gets no keys
The lock script was not detected: it starts after Lifeguard Job, or it is not one of the eleven supported. Move it up in server.cfg, or add a bridge as shown in Integrations.
I added a call-out to the config and it never happens
Each call-out id is played by a scene built into the job, so a new id has nothing to play. Tune, move or switch off the sixteen that ship instead — see Call-out IDs.
Cooperative Rescues#
A cooperative rescue never happens
It needs Config.CoopIncidents.enabled, at least two lifeguards who started their shift at a station, and then a 30% roll on someone's checkpoint arrival — with a 10-minute rest after each one (5 after a failure). The Shared calls page of the settings panel shows how many are on shift, and can start one on the spot to test.
A lifeguard on the rescue was not paid
A cooperative rescue pays for the work each lifeguard did: somebody who found no board, delivered no surfer, rescued no passenger or never drove off a shark has nothing to be paid for. A lifeguard who changed job during it is not paid, and a Shark Alert that loses every swimmer pays nobody.
Statistics and Levels#
The statistics board stays empty
It fills in as solo call-outs are paid — cooperative rescues are not counted on it. It is saved to data/stats.json, so the server needs write access to the resource folder; on hosts that mount resources read-only it cannot be kept.
A player's level went back to 1
Levels are kept per character — the ESX identifier, or the citizen id on QBCore and Qbox — so a different character starts from 1. Their row is in qs_lifeguard.
The leaderboard shows the wrong name
It follows Config.PlayerNameSource — the character's name, the FiveM name, or both. A name is stored when a call-out is paid, so a change shows after that player's next one.
When the Settings Panel Refuses a Change#
Every change is checked on the server before it is saved. One that is refused is not lost: the panel briefly marks the save as failed and the edit stays pending, so you can see it and correct it. The usual causes:
What you see | Why, and what to do |
|---|---|
"You are not allowed to do that" | The player lacks the panel's ACE. It is checked on every button, not only when the panel opens. |
A value will not save | It is not the same kind as the file's — text where a number belongs, or a list reshaped into something else — or it is not one of the answers the setting accepts. Match the kind of value the file has there. |
Nothing will save at all | The database refused the write. The server console prints |
The framework or lock script is not offered | Both are detected at every start and cannot be saved. Change the load order instead. |
Start does nothing on Shared calls | Shared calls are switched off, fewer lifeguards are on shift than one needs (the counter on the page says how many), or one is already running. |
Saved, but the game still runs the old value | Expected: saved settings wait for |
Console: saved setting(s) no longer fit this config | After an update, a setting saved earlier no longer matches the new config file and is ignored. It is kept in the database; revert it from the panel to clear it. |
Still stuck? Open a ticket and include your framework, the order of your
server.cfg, and the server and F8 console output withConfig.Debugon while you reproduce the problem.



