What goes wrong most often, what it actually means, and what to do about it. For anything not listed here, set Config.Debug = true and restart: the console then prints every infection and every infect-window timeout as it happens.
Installation and Access#
"You are not allowed to use the Biohazard creator."
The player does not have the ACE command.biohazardcreator. Add both lines from Installation to server.cfg, check that the license: in add_principal is that player's, and restart the server. If you renamed the command with Config.CreatorCommand, the permission is renamed with it.
"Failed to save the event preset."
The database refused the write — almost always because the tables do not exist. Import [sql]/biohazard.sql, make sure oxmysql starts before qs-biohazard, and restart. A healthy boot prints [Biohazard] Loaded N saved event preset(s). with no oxmysql error above it.
/biohazard does nothing
That command belonged to the first version and was removed in 2.0. Outbreaks are started and stopped from /biohazardcreator, or by Auto Start.
My translation is not used
The file name must match Config.Language exactly — locales/fr.json for 'fr' — and be valid JSON. A single syntax error, such as a trailing comma, makes the whole file be ignored and English is shown instead. Run it through a JSON validator.
An outbreak started on its own
That is Auto Start, which ships on. It launches a random preset — or the default template if you have none — every two to five hours. Set Config.AutoStart.Enabled = false to only run outbreaks by hand.
During an Outbreak#
No zombies spawn
Zone event: zombies only spawn for players standing inside the zone. Walk in.
Zone too small: a spawn needs a spot inside the polygon at least 8 m from the player. Draw it wider.
Horde set to nothing: Base horde size and Extra per player both at 0, or Max zombies already reached.
Something deletes them: an anti-cheat or entity-cleanup script that removes networked peds. Whitelist qs-biohazard in it.
Zombies ignore a player
Usually on purpose. The horde holds off while the intro is on screen, never chases a player who is outside the zone, and gives up on anyone more than 400 m away (Config.AI_MaxChaseDist). Players your death system marks as dead are ignored too.
The weather or the clock keeps changing back
A weather or time sync resource is overriding the outbreak every few seconds. Pause it while an outbreak runs by listening to biohazard:start and biohazard:stop (see Commands and Exports), or turn off Force weather and Freeze time for that event.
Infected players die after a while
That is the infect window: a zombie player who infects nobody in time drops and comes back human. Raise Infect window, or turn off Zombie dies if it does not infect in time, in the event's Infection section. On zone events the window pauses while they are outside the zone.
Survivors cannot die
By design: during an outbreak a human's health is held above Config.HPMinSafety (125), so the horde infects them instead of killing them. Set it to 0 to let survivors die normally.
Players keep the zombie look, or lose their clothes, after the event
Their clothing script was not asked to reload. ReloadSkin calls qs-appearance; with another clothing script, change it as shown in Integrations.
A zombie player who is shot down stays down
Your ambulance script does not listen for ambulance:revivePlayer. Add the bridge from Integrations to client/custom.lua with your script's revive event.
The intro or the ending does not show
Check Enable intro/outro visual in the event's Ambience section and enable in Config.IntroImage / Config.EndImage. On zone events the intro plays when a player first walks in, and the ending only for players inside the zone when it ends.
Rewards, Levels and the Scoreboard#
Survivors receive nothing
Either Reward survivors is off for that event, or GiveReward has not been connected to your framework — the shipped version only prints [Biohazard] Survivor reward for … in the console. If that line appears, the event part works; replace the function as shown in Integrations.
The scoreboard key does nothing
With OnlyDuringEvent on, it only opens while an outbreak runs, and on zone events only inside the zone. The player may also have rebound it under Settings → Key Bindings → FiveM — and a new Config.Scoreboard.Key only applies to players who have never joined before.
The leaderboard shows FiveM names, or progress is shared between characters
Out of the box, progression is kept per Rockstar license with the FiveM name. Replace GetIdentifier and GetDisplayName with your framework's version from Integrations — preferably before players build up XP, since records are keyed by the identifier.
Nobody gains XP
Check Config.Levels.Enabled and that the qs_biohazard_stats table exists. XP is only written when an outbreak ends, never during it.
The phone app is empty
phone-biohazard must be running alongside qs-smartphone. It is detected live, so starting it fixes the app without restarting Biohazard Creator. The profile and leaderboard also need Config.Levels.Enabled, and outbreak types need Config.Phone.ExposePresets.
Still stuck? Open a ticket and include the server console from boot (the
[Biohazard]lines), the F8 console of an affected player, and yourconfig.lua.



