Troubleshooting

Almost everything has an answer in the server console. Start there.

A Healthy Start

With F5Cfg.Debug = false a clean boot prints exactly two lines:

[f5_combathud] Config validated.
[f5_combathud] MySQL bridge: oxmysql

What you see instead	What it means
Config loaded with N warnings.	Running, but something in config/ deserves a look — each warning names its own key
CONFIG INVALID — N errors. Resource will not start.	Not running — the resource stops itself. Fix the errors listed above that line
No MySQL bridge: line	The database layer never came up — see nothing saves
None of these lines at all	The shared scripts never ran: the resource is stopped, or the folder is in the wrong place

A start that created or repaired the database prints more — the tables and columns it added, then Database schema ready (N tables). That is normal on a first run and after an update.

Turning on F5Cfg.Debug = true in config/main.lua adds per-kill, per-hit, per-save diagnostics on both consoles. Turn it off again afterwards — it makes the client do extra work per hit.

The Resource Will Not Start

All of these are printed by the server; the client never validates the config.

CONFIG INVALID — N errors

Each error names the key. The common ones:

Message	Cause
F5Cfg.EnableKillFeed must be true or false, got nil (config/features.lua)	A feature flag was commented out, deleted or misspelled. All 15 must be a real boolean
F5Cfg.Framework.mode = "qbcore" is not one of: auto, qb, qbx, esx, custom	Use qb, not qbcore; qbx, not qbox
F5Cfg.Locale must be a non-empty language code (config/main.lua)	Locale is empty or not a string
F5Cfg.Command must be a non-empty command name	Without it there would be no way to open the menu
F5Cfg.Profiles.maxProfiles must be at least 1	Use Profiles.enabled = false to switch profiles off
F5Cfg.ShareCodes.effectsPrefix duplicates prefix "CR_" from crosshairPrefix	Two share-code prefixes are identical — codes would be misrouted
F5Cfg.Validation.size.min (100) is above F5Cfg.Validation.size.max (50)	A reversed range would freeze that field at its minimum
F5Cfg.CrosshairSections must be a table	A section table was replaced by something else

missing required config: F5Cfg.Profiles.maxProfiles must be a number

Checked before everything else. F5Cfg.Profiles must exist and maxProfiles must be a number.

no supported framework detected

[f5_combathud][bridge] no supported framework detected (qbx_core, qb-core, es_extended) — set F5Cfg.Framework.mode in config/main.lua

Detection runs once, at load. Unlike the database layer, it does not retry — a framework that starts later is never picked up.

1. Put ensure f5_combathud after your framework in server.cfg.
2. If your core resource has a different name, use mode = 'custom' with a matching base — see Framework Compatibility.

A related pair:

[f5_combathud][bridge] F5Cfg.Framework.mode = "esx", but resource es_extended is not running — start it before f5_combathud, or set mode = 'auto'
[f5_combathud][bridge] cannot reach the es_extended core object — make sure that resource starts before f5_combathud

The first is a warning — the resource carries on with that adapter and then cannot reach anything. Same fix: boot order.

DATABASE SCHEMA INCOMPLETE — the resource will not run.

The resource stops itself on purpose, and names what is missing. Two causes:

• The database user lacks CREATE / ALTER rights. Grant them, or set AutoInstallDatabase = false and import install.sql by hand.
• install.sql was reformatted. The resource parses that file to learn the schema and needs one column per line. Restore the original.

See Database.

install.sql not found / install.sql contained no statements.

[f5_combathud] install.sql not found — cannot create the database schema.
[f5_combathud] Could not read install.sql — cannot verify the database schema.

The resource stops itself rather than running with nothing saved. Restore install.sql from the download; it must sit in the resource root, unedited.

The Menu Opens but Nothing Works

The classic symptom: /chud opens, sliders move, nothing is ever saved.

Look at the server console. Every startup failure above stops the resource, so the usual cause is that it is simply not running any more — scroll up for the reason.

A resource caught mid-abort logs this on the server for the moment before it stops:

[f5_combathud][bridge] no server callback registered: f5_combathud:server:getData

If instead the client console shows:

[f5_combathud][bridge] server callback timed out after 60s: f5_combathud:server:getData

then the server is not answering at all — usually the resource is stopped on the server, or was stopped by the schema check.

The resource folder was renamed

The menu opens and looks perfect, but no button does anything. The NUI addresses its callbacks to the literal name f5_combathud.

Rename the folder back — or change that one string in html/script.js (see NUI & Assets).

Nothing Shows Up In Game

Everything ships switched off. A fresh player has no crosshair, no hitmarker, no K/D, no kill feed until they open /chud and turn things on. This is the single most common "it does not work" report.

To have something on from the first join, change the enabled values in config/defaults.lua — that applies to new players, not to anyone who already has a row.

The crosshair is the one exception: a player with no database row yet starts with it off whatever the default says, until a row exists for them — after their first kill or death, or after they toggle the crosshair once. Every other feature honours its default immediately.

Then check, in order:

1. Is the feature's Enable* flag true in config/features.lua?
2. Is the player's own toggle on in the menu?
3. For the Scoreboard tab: EnableScoreboard plus at least one of EnableKillstreak / EnableKDHud / EnableKillFeed.

Every section says "disabled by server admin"

[f5_combathud] features._v=9 exceeds NUI build (8); falling back to safe defaults

(in the CEF/browser console). The html/ folder is older than the Lua code — a partial update. Ship the matching html/script.js.

Settings Are Not Saving

No database layer

[f5_combathud] No MySQL resource detected (oxmysql / mysql-async / ghmattimysql)

The resource then stops itself, for the same reason an incomplete schema stops it: left running, the menu would open, the crosshair would work from client memory, and every write would return early — players would lose everything at their next relog.

The database layer waits 30 seconds for a driver, so a slow oxmysql is fine — a missing or misnamed one is not. Make sure ensure oxmysql comes before ensure f5_combathud.

It saved, then it did not

• Saves are limited to one per player every 2 seconds. A save that arrives inside that window is dropped outright — no queue, no retry, no message. Editing in the menu is paced above that window and is safe; what can be lost is a save triggered outside it — the F9 toggle, a reset, applying a marketplace crosshair, importing a share code or restoring a backup, when it lands right after an autosave. Doing one of those, then waiting a couple of seconds before closing the menu, is enough.
• "SAVED" in the menu means "sent", not "stored". The badge appears as soon as the request leaves.
• No "Settings saved successfully" notification is normal. That message only comes from the menu's Save button and the reset action; autosaves are silent by design. Even on those two paths, re-saving settings that did not change writes no row and shows nothing.

It saves, but the value is not what the player set

• The value was clamped to a range in config/limits.lua. Almost nothing is rejected; out-of-range numbers become the nearest legal value, and unknown styles fall back to a fixed default.
• The section is switched off in config/features.lua. Disabled sections are pinned or cleared on every save — see the enforcement table.
• The player is in a group with a SectionOverrides entry.

Profiles

Symptom	Cause
"Maximum profiles reached (5)"	Profiles.maxProfiles. Lowering it never deletes anything — a player over the limit keeps their profiles and can still overwrite them
The profile list is empty and no error appears	Either Profiles.enabled = false, or the schema is not ready. Both look identical from the menu
A profile cannot be renamed	There is no rename. Save under a new name and delete the old one
Saving a profile does nothing	The name is empty after trimming, or longer than 50 characters

K/D Is Not Counting

Everything below must be true:

1. EnableScoreboard is not false, and EnableKDHud is true.
2. Either CountNPCKills = true, or the player has the K/D display switched on in their menu and the victim was a real player.
3. The schema is ready.

The second one catches people out

With CountNPCKills = false, a player who never enables the K/D display never records a single kill or death. If you want stats regardless of the display, set CountNPCKills = true.

K/D is stored per account, not per character, so every character shares one score. Kills and deaths cannot be set through a settings save; a player can only reset their own from the menu.

Kill Feed Problems

Symptom	Cause
The feed shows nothing	EnableKillFeed off, the player's own toggle off, or the schema is not ready
Only your own kills appear	Show all kills is off by default. That is per player
Deaths from falls or crashes do not appear	ShowNPCKillsInFeed = false
A weapon shows as [weapon_something]	The icon images/icons/<name>.png is missing — see NUI & Assets
The weapon name is wrong or absent	The framework's weapon list has no entry for that hash. On QBox the list is cached per session, so a runtime addition needs a reconnect
Avatars are blank	set steam_webApiKey "…" is missing from server.cfg — the console says so at startup
Entries stop during a firefight	The feed is rate-limited to a burst of 8 entries, refilling 2 per second per player

Killstreak Is Silent

• A tier only fires on an exact kill count. With tiers at 6 and 8, a seventh kill announces nothing.
• The window between kills is Killstreak.timeout — 15 seconds by default. A slower kill starts a new streak at 1.
• Sounds need the player's own sound toggle on, plus sound = true and a soundFile on that tier.
• With NPCKillsCountStreak = false, NPC kills neither extend nor reset a streak.

Marketplace

Symptom	Cause
The tab is missing	EnableMarketplace is not exactly true
The tab is there but everything answers "Marketplace is disabled"	F5Cfg.Marketplace is missing or is not a table
"You are not allowed to moderate the marketplace"	The player matches no entry in ModeratorAces — see Permissions
The Moderation tab does not appear after granting an ACE	The player's menu asks for its permissions once per session. A reconnect is the reliable way
"Too many requests"	Publish and edit are limited to one per 3 seconds
"Listing not found" when applying	The listing was deleted or hidden by a moderator — the two look the same to a player
A listing shows no picture	One page of results carries at most 2 MiB of images; the rest arrive without theirs
Nothing beyond a few hundred pages	Results past 5000 rows are unreachable by design

The Custom Image Is Refused

Message	Cause
Image too large after encoding. Pick a smaller file.	Over imageDataMaxBytes (512 KB encoded ≈ 384 KB file)
Invalid file type. Use PNG, SVG, JPG or WEBP.	The menu accepts those four only
Only https:// URLs are accepted	Plain HTTP is always refused
That host is not allowed	allowedUrlHosts does not list that host. Matching is exact — imgur.com does not cover i.imgur.com
The image could not be downloaded from that URL	At publish time, the server fetches the picture itself and the fetch failed
That link does not point to a supported image file	The content type or the file's own bytes are not PNG / JPEG / GIF / WEBP / SVG
Custom image crosshairs cannot be published on this server	MarketplaceSections.publishCustomImage = false. It triggers on a profile that carries image data, even if the image is switched off

A URL image that never appears in game is usually the host: some image hosts refuse requests coming from the FiveM client even though the same link works in a browser. Try a different host.

A picture that vanishes after a save means the data URI failed server-side validation — it is stored empty rather than rejected. Re-upload from the menu rather than pasting data by hand.

A picture that vanishes for everyone means CrosshairSections.customImage was set to false: that clears the stored image and the URL on every save and load.

Share and Backup Codes

Message	Cause
Share code type is disabled by server admin	That code type is off — or the prefix does not match any configured type
Invalid or corrupted code	Wrong prefix, over 4096 characters, or built by a different version
Invalid backup code format	The code does not start with Backup.prefix
Rate limit exceeded	Imports are limited to a burst of 3, refilling one every two seconds

Changing a prefix invalidates every code already in circulation

There is no migration. Old codes are simply rejected.

An imported crosshair that "looks different" is expected: a crosshair code does not carry glow, rainbow, animation, HP colour, the centre dot, ADS behaviour or the image. Those stay at the importer's own settings.

Sounds Are Silent

1. The player's own sound toggle for that effect — all of them ship off.
2. The file must be Ogg, and must sit in html/sounds/ or html/sounds/killstreak/. The manifest streams nothing else, and a missing file produces no error at all.
3. soundFile in config/defaults.lua is relative to html/sounds/.

Fonts Are Not Applying

A font must be in both F5Cfg.Validation.Fonts and the Google Fonts link in html/index.html. In the whitelist only, the browser silently substitutes something else; in the link only, it never appears in a dropdown. See NUI & Assets.

The Menu Looks Wrong

The interface loads its icon font and its animation library from external CDNs. On a machine with no access to them the menu still works — it renders without icons, and without animations. If your players' menus look plain, that is why.

Discord Gets Nothing

[f5_combathud] MarketplaceWebhook.enabled = true, but url is still the placeholder …

Otherwise, in order:

1. logEvents for that event must be exactly true — 1 or 'yes' disables it.
2. A mistyped URL produces no startup warning. Watch for webhook failed (status: 401, attempts: 1) after a real publish.
3. With the marketplace disabled nothing is logged, because no event is ever reached.
4. There is no test command; a real marketplace action is the only way to check.

See Webhooks.

Firewall and Outbound HTTP

The resource makes outbound requests to three places, all optional:

Endpoint	Used for
discord.com	The marketplace webhook
api.steampowered.com	Avatars, only when steam_webApiKey is set
Any HTTPS host a player names	Fetching a URL crosshair when it is published to the marketplace

Still Stuck

Collect this before opening a ticket:

• The server console from resource start, with F5Cfg.Debug = true.
• Your framework and its version, and your database resource.
• Whether Config validated. and MySQL bridge: both appear.
• What you changed in config/ most recently.

See Also

• Installation — boot order and first-run checks
• Configuration — every key and what it enforces
• Database — schema, saving, retention
• Permissions — moderator access
• NUI & Assets — fonts, sounds, icons