Troubleshooting

Common Issues

Safezone not activating when entering the area

Possible causes:

• Zone is deactivated (check data/zone_states.json)
• Framework not fully loaded before the resource starts
• Config.CheckInterval is set too high

Fix:

1. Check if the zone is active:

/listsafezones

Look for [Active] or [Inactive] tags.

2. Ensure f5_safezones starts after your framework in server.cfg:

server.cfg

ensure qb-core   # or qbx_core / es_extended
ensure f5_safezones

3. Try lowering the check interval:

config.lua

Config.CheckInterval = 100 -- Default, lower = more responsive

Players can still deal damage inside safezones

Possible causes:

• Zone has enableInvincibility set to false
• Another resource is re-enabling damage on the player (e.g. calling SetEntityInvincible(ped, false) on a timer)

Fix:

1. Check zone protection settings (enableInvincibility is what protects players from damage):

enableInvincibility = true,
disableVehicleWeapons = true,
collisionDisabled = true,

2. Check for resource conflicts — any script that sets SetEntityInvincible(ped, false) on a timer will override safezone protection.

3. Enable debug mode to verify the zone boundaries:

/szdebug

Players or vehicles still collide (no pass-through)

Pass-through is controlled only by collisionDisabled (default true). enableGhosting no longer affects collision — it is transparency only.

Possible causes:

• collisionDisabled is set to false on the zone
• The other player is not registered as being in the same zone by the server (position verification failed — see below)
• A vehicle straddles the zone edge so its centre is outside the zone volume (only vehicles whose centre is inside the zone are included)

Fix:

1. Ensure the zone has collisionDisabled = true (it is the default; only false turns pass-through off).
2. Confirm both players are actually inside the zone. Membership is server-authoritative — if the server rejects a player's entry (see position verification), that player is not ghosted for anyone.
3. For a large vehicle sitting on the boundary, move it fully inside the zone.

Transparency vs pass-through

If you wanted the semi-transparent look, that is enableGhosting / enableVehicleGhosting (both off by default). They do not control collision — leaving them off still lets entities pass through each other, just fully opaque.

Admin panel won't open

Possible causes:

• Player doesn't have the required ACE permissions
• The /szadmin command is disabled in config
• NUI is not loading (check F8 console for errors)

Fix:

1. Verify admin permissions — try from the server console:

listsafezones

If this works but /szadmin doesn't, it's a permission issue.

2. Check that the command is enabled:

config.lua

Config.Commands.szadmin = {
    name = 'szadmin',
    active = true,
}

3. Grant the proper ACE permission:

server.cfg

add_ace group.admin safezones.admin allow

Zones disappearing after server restart

Possible causes:

• Custom zones file (data/zones.json) is corrupted or permissions error
• The data/ directory doesn't exist or isn't writable

Fix:

1. Check if data/zones.json exists and contains valid JSON
2. Check the data/zones.json.backup file — restore from it if the main file is corrupted
3. Ensure the server process has write permissions to the data/ directory
4. Check server console for error messages about file operations

Zone markers not rendering

Possible causes:

• showMarker is false for the zone
• Player is outside renderDistance
• Marker type is set to an invalid value

Fix:

1. Toggle marker visibility:

/sztoggle

2. Check render distance — move closer to the zone center
3. Verify marker type is between 1-6:

config.lua

Config.DefaultMarker = {
    type = 1, -- Must be 1-6
}

"Access denied" for all admin commands

Possible causes:

• No matching ACE permission
• Framework permission level not granted

Fix:

Check which permission system you use:

ACE Permissions

server.cfg

# Grant specific permission
add_ace identifier.steam:110000xxx safezones.admin allow

# Or grant to admin group
add_ace group.admin safezones.admin allow
add_principal identifier.steam:110000xxx group.admin

QBCore

Ensure the player has admin or god permission in QBCore:

QBCore.Functions.AddPermission(source, 'admin')

ESX

Ensure the player has admin or superadmin group in ESX:

-- In your ESX admin management
xPlayer.setGroup('admin')

QBox Core

QBox uses ACE permissions only. Grant via server.cfg:

server.cfg

add_ace identifier.steam:110000xxx safezones.admin allow

txAdmin

If using txAdmin, the command.tx ACE is automatically checked:

server.cfg

# txAdmin usually sets this automatically
add_ace identifier.steam:110000xxx command.tx allow

Server-side position verification rejecting valid entries

The server verifies player positions with a 5-unit tolerance. If players are frequently being rejected:

• Check for high network latency on your server
• The issue may be caused by teleportation scripts that move players just before they enter a zone
• Check server console for Rejected safezone entry messages with position data

Performance Issues

High CPU usage from safezones

1. Increase check intervals:

config.lua

Config.CheckInterval = 200         -- Increase from 100ms
Config.Performance.updateIntervals = {
    playerCache = 1000,             -- Increase from 600ms
    markerList = 2000,              -- Increase from 1000ms
    collisionCheck = 800,           -- Increase from 450ms
}

2. Reduce collision range:

config.lua

Config.CollisionSystem.range = 50.0  -- Reduce from 100m

3. Disable marker effects:

config.lua

Config.DefaultMarker.pulsing = false
Config.DefaultMarker.bobbing = false
Config.DefaultMarker.rotating = false
Config.DefaultMarker.colorShift = false

4. Use render distance limits:

renderDistance = 80.0,              -- Don't render markers from far away

FPS drops when inside a safezone with many players

Pass-through re-applies no-collision every frame for the local player against every zone member, so cost scales with the number of players and vehicles in the zone. For busy areas:

1. Increase collisionCheck and vehicleEnforce intervals
2. Reduce Config.CollisionSystem.range
3. If pass-through is not needed for a zone, disable it: collisionDisabled = false (this is the per-frame work; enableGhosting is only transparency and is off by default)

Debug Mode

Enable debug mode to diagnose issues:

config.lua

Config.Debug = true

This outputs detailed information about:

• Zone loading and validation
• Player enter/exit events with position data
• Collision system entity counts
• Network event processing
• Admin permission checks

Selective Debugging

Disable noisy categories to focus on specific issues:

config.lua

Config.DebugCategories = {
    INIT = false,        -- Disable startup noise
    ZONE = true,         -- Keep zone info
    COLLISION = false,   -- Disable collision spam
    NETWORK = true,      -- Keep network events
    ADMIN = true,        -- Keep admin events
    ERROR = true,        -- Always keep errors
}

Still Need Help?

Open a ticket on our Discord server with:

• Your framework (QBCore / QBox / ESX) and version
• Server build number
• F8 console output (client-side)
• Server console output
• Your config.lua (remove sensitive ACE data)
• Steps to reproduce the issue

See Also

• Installation — verify your setup step by step
• Configuration — check all config options
• Debug & Logging — enable detailed diagnostics
• FAQ — common questions about all F5 Studio scripts