Troubleshooting

Connection Issues

Symptom: "Failed to connect to radio server" or health check errors:

[Radio-Server] ERROR Health check failed after 4 attempt(s)
[Radio-Server] WARN HTTP endpoint test failed - connect ECONNREFUSED

Port Testing

Start the radio resource
Go to portchecker.co
Enter your server IP and port
Open = configured correctly | Closed = port is blocked

Web Panel Hosting

Common with Pterodactyl-Based Hosts

Many providers (Gravel Host, RocketNode, VibeGames, etc.) require a support ticket to actually open the port, even after adding it in the panel.

Verify the port is added in your panel's Network/Ports/Allocations section
Confirm you are not using port 30120 (FiveM) or 40120 (txAdmin)
Set both serverPort and serverAddress in config.lua
Restart the entire server from the panel
Test with portchecker.co
If still closed, open a support ticket

VPS / Dedicated Server

Ubuntu/Debian:

sudo ufw allow 7777
sudo ufw reload

CentOS/RHEL:

sudo firewall-cmd --permanent --add-port=7777/tcp
sudo firewall-cmd --reload

Windows Server:

netsh advfirewall firewall add rule name="Radio Voice Server" dir=in action=allow protocol=TCP localport=7777

Checklist

fx_version 'bodacious' in fxmanifest.lua
Port not in use (not 30120 or 40120)
serverPort and serverAddress use the same port
Resource starts without errors
Tested with portchecker.co while resource is running

Error Reference

Error	Cause
ECONNREFUSED	Port blocked, wrong IP/port, or firewall issue
Invalid URL	Wrong `serverAddress` format — try `serverAddress = ""`
xhr poll error	Port not accessible from the internet

Health Checks Failing Despite Working Panel

As of v5.7, the startup healthcheck runs a two-stage probe and reports one of three states:

State	Meaning
Green	Both the public URL and `127.0.0.1` probes succeeded — fully operational.
Amber (warning)	Localhost probe passed, public probe failed from this host. Service is up; this host just can't reach its own public IP.
Red (error)	Both probes failed. The service is not running, is on the wrong port, or is being shadowed by another process.

Amber Warning

If you see this line in the console, it is a warning, not a failure:

Port X reachable on localhost but public probe failed from this host — likely hairpin-NAT or split-horizon DNS. Verify from a remote client; if players connect, this warning is cosmetic.

Common causes:

Router without NAT reflection (hairpin-NAT) — most consumer routers can't route LAN → public IP → LAN
CGNAT — your ISP puts you behind carrier-grade NAT, so your "public" IP is not actually reachable from inside the network
Split-horizon DNS — your public hostname resolves to a different address from inside the LAN
Reverse proxy on a different port — e.g., Cloudflare or nginx terminates on 443 and forwards to the radio port internally, so a direct probe to the radio port from this host doesn't match the expected response
Restrictive outbound firewall — the server host can't initiate connections back to its own public IP

If amber, the radio works for players

Verify from outside your LAN (phone on mobile data, or an external tool like portchecker.co) before chasing the warning. If players can connect, the warning is cosmetic.

Red Error

In v5.7+, the red error is emitted only when both the public probe and the localhost probe fail, so it's much more actionable than before. The two possible messages are:

Port X is not reachable from the public internet (see link below)

Port X is reachable but another service is responding — check that radioPort is not shared with txAdmin or another resource (see link below)

When either appears, the service is almost certainly not running on the configured port, or the port is being answered by something else (txAdmin, another resource, a stale process). Work through the sections above.

Real failure signs

ECONNREFUSED, EACCES, EADDRINUSE, or players can't connect in-game → investigate via the sections above.

Microphone Issues

Open radio > ST > navigate to microphone setting > select a different device
Check FiveM permissions — ensure you clicked "Allow" for microphone access

Permission Reset

If you denied microphone permission, clear FiveM cache to get the prompt again.

Dispatch Panel

NAC Code Doesn't Work in Desktop App

The desktop app defaults to the demo server. Change the endpoint:

Open app, login with 141 (demo default)
Click the settings cog at top-right
Change Endpoint URL to http://YOUR_IP:YOUR_PORT/
Save — app refreshes
Login with your dispatchNacId

"Where Do I Get the NAC Code?"

You create it in config.lua:

Config = { dispatchNacId = "DISPATCH2024" }

Symptom	Solution
No voice at all	Check NAC ID has channel access in `allowedNacs`
No background effects	Enable `playTransmissionEffects` in admin panel
Volume too low	Adjust `voiceVolume` / `sfxVolume` in admin panel
Unwanted bonk tones	Disable `bonking.playBonkTone` in admin panel
Players talking over each other	Enable `bonking.blockTransmission` in admin panel
No radio character at all	Check `radioFx.fxEnabled` or `radioFx.p25Enabled` in admin panel

P25 / IMBE Vocoder

Symptom	Solution
Robotic/warped at start of transmission	Normal — WASM vocoder warming up, self-resolves after first PTT
Metallic buzz / warbling	Reduce mic gain in Windows sound settings (input clipping)
Voice sounds muffled with P25	Disable `radioFx.fxEnabled` if both P25 and analog FX are active
First syllable cut off	Normal codec behaviour (< 10ms). Adjust `pttReleaseDelay` if severe
Dispatch hears clean Opus instead of P25	Confirm `p25Enabled = true` and refresh dispatch panel
WASM failed to load (dispatch console)	Check resource is running and `/radio/imbe_vocoder.wasm` is accessible

Analog FX Chain

Symptom	Solution
Too muffled / telephone-like	Raise `lowpassFrequency` (try 4000-5000) or lower `compression`
Too tinny / harsh	Lower `highpassFrequency` (try 150-200) or reduce `midBoost`
Volume pumping	Lower `compression` (try 30-40)
Distorted / crackling	Lower `inputGain` (try 0.8-1.0) or lower `distortion`

Emergency Features

Issue	Fix
Can't activate Signal 100	NAC ID must match `dispatchNacId`
Panic not visible	Check `gps.visibleToNacs` in channel config
No emergency sounds	Enable `playTransmissionEffects` in admin panel

GPS & Tracking

If GPS blips aren't showing:

Check NAC permissions: gps.visibleToNacs in channel config
Enable GPS in radio settings (ST menu)
Verify the channel has GPS configured

Configuration Issues

Issue	Fix
Can't connect to channel	Check `allowedNacs` includes the player's NAC ID
Can't scan channel	Check `scanAllowedNacs` includes the player's NAC ID
Can't see zone	Add NAC ID to the zone's `nacIds` array
Wrong permissions	Review `getUserNacId` function logic

Syntax Error: `<\1>`

Two common causes:

Corrupted file transfer — Some FTP clients (FileZilla in ASCII mode) or Remote Desktop drag-and-drop can corrupt files. Use WinSCP or set binary transfer mode. Always transfer the .zip and unzip on the server.
Outdated server artifact — must be build 4752 or higher

Check Server Version

Type version in your server console.

Update Server

Windows: Download latest recommended artifact from the FiveM build server

Linux:

Download latest artifact from the Linux build server
Stop server, delete cache and alpine folders
Extract: tar -xf fx.tar.xz
Start and verify with version

Missing `.fxap` File

For Asset Escrow scripts, the .fxap file is hidden (dot-prefixed). Enable "show hidden files" in your FTP client. Ensure .fxap is not excluded by .gitignore in CI/CD pipelines.

Debug Logging

Set Config.logLevel in config.lua:

Level	Output
0	Errors only
1	Warnings
2	Minimal
3	Normal (default)
4	Detailed
5	Verbose

Levels 4-5 produce extensive output. Use only for active troubleshooting.

Support

Before asking for help:

Check server console for errors
Test on the demo server
Verify port is open with portchecker.co

Forum: FiveM Community Post

When reporting issues, include:

Console error messages
Relevant config.lua sections
Server framework (QBCore, ESX, etc.)