"Debugging FiveM Resources: A Practical Guide"

Every FiveM developer runs into the same bugs. Here's a practical guide to the most common issues and how to fix them — with and without AI.

1. "Attempt to index a nil value"

This is the most common error in FiveM, and it almost always means something wasn't initialized before you tried to use it.

Framework Not Started First

If your resource depends on QBCore or ESX, it must start after the framework:

lua

-- fxmanifest.lua — declare dependency
dependency 'qb-core'

Even with the dependency declared, exports may not be ready on the first tick:

lua

-- Server-side: exports not ready in first frame
Citizen.CreateThread(function()
    Wait(1000)
    local QBCore = exports['qb-core']:GetCoreObject()
end)

Player Object Is Nil

This happens when a player hasn't fully joined but their source is already being used:

lua

RegisterNetEvent('myresource:someEvent', function()
    local Player = QBCore.Functions.GetPlayer(source)
    if not Player then
        return  -- Player hasn't spawned yet
    end
end)

The fix: always guard player access checks. If you're using FiveForge, paste the full error trace with surrounding code and the AI can pinpoint exactly which module isn't loaded.

2. Events Not Firing

Events are the backbone of FiveM communication. When they silently fail, here's what to check:

Client to Server

lua

-- Client
TriggerServerEvent('myresource:buyItem', itemData)

-- Server — name must match exactly, case-sensitive
RegisterNetEvent('myresource:buyItem', function(data)
    -- This won't fire if the name is wrong
end)

Server to Client

lua

-- Server
TriggerClientEvent('myresource:showNotification', source, message)

-- Client
RegisterNetEvent('myresource:showNotification', function(msg)
    -- Handler
end)

The Three-Line Debug

When an event isn't firing, add these temporarily:

lua

-- In the triggering file
print("[TRIGGER] myresource:buyItem fired for source " .. source)

-- In the receiving file
RegisterNetEvent('myresource:buyItem', function(data)
    print("[RECEIVE] myresource:buyItem received")
    -- Your code
end)

If you see TRIGGER but not RECEIVE, the event name or file path is wrong.

3. qb-target Interactions Not Showing

qb-target zones that don't appear are almost always one of three things:

lua

exports['qb-target']:AddBoxZone("weapon_shop", vector3(22.04, -1105.56, 29.8), 2.0, 2.0, {
    name = "weapon_shop",
    heading = 0,
    debugPoly = true,  -- Set true during development
    minZ = 28.8,
    maxZ = 30.8,
}, {
    options = {
        {
            type = "client",
            event = "myresource:openShop",
            icon = "fas fa-gun",
            label = "Open Weapon Shop",
        },
    },
    distance = 2.5,
})

Debug checklist:

debugPoly = true — shows the zone wireframe so you can see its position and size
Start order — qb-target must start before your resource. Check server.cfg
Target resource present — verify qb-target exists in your resources folder
Options match — ensure the event name in options matches your registered handler

4. Database Query Failures

Database errors usually look like ERROR: Query failed: INSERT INTO ... with a SQL error code.

Parameterized Queries (QBCore)

lua

MySQL.Async.execute('INSERT INTO player_vehicles (license, citizenid, vehicle) VALUES (@license, @citizenid, @vehicle)', {
    ['@license'] = license,
    ['@citizenid'] = citizenid,
    ['@vehicle'] = json.encode(vehicleData),
}, function(rowsChanged)
    if rowsChanged > 0 then print("Vehicle saved") end
end)

Common Pitfalls

Symptom	Cause	Fix
"Column not found"	Column name in query doesn't match your schema	Check your `CREATE TABLE` statement
"Unknown column"	Typo in column name	Use backticks for reserved words
Data looks wrong	JSON objects inserted as `[object Object]`	Always use `json.encode()` before string columns
"Table doesn't exist"	Missing `oxmysql` or `mysql-async` resource	Add to `server.cfg` before your resource

5. Performance Bottlenecks

The Expensive Loop

lua

-- BAD: runs every frame
Citizen.CreateThread(function()
    while true do
        for _, id in ipairs(GetPlayers()) do
            local Player = QBCore.Functions.GetPlayer(id)
            -- Expensive operation 32 times per frame
        end
        Wait(0)
    end
end)

-- GOOD: runs periodically
Citizen.CreateThread(function()
    while true do
        Wait(5000)  -- Every 5 seconds
        for _, id in ipairs(GetPlayers()) do
            local Player = QBCore.Functions.GetPlayer(id)
        end
    end
end)

The 500-Entity Raycast

Every GetPlayers() call and every loop iteration has a cost. With 48 players and 10 resources all looping every frame, you're processing 480 iterations per tick. The rule of thumb: if your loop doesn't need sub-second precision, add a Wait().

Event Registration in Loops

lua

-- BAD: registers a new handler every frame
Citizen.CreateThread(function()
    while true do
        RegisterNetEvent('myresource:onEvent', function() end)
        Wait(0)
    end
end)

-- GOOD: register once at file scope
RegisterNetEvent('myresource:onEvent', function() end)

6. AI-Assisted Debugging

Instead of searching forums for every error, try giving FiveForge full context:

"Explain why my qb-target interaction isn't showing. Here's my config and surrounding resource structure."

Or for elusive performance issues:

"Find performance issues across my resources. Flag any resource using Wait(0) in main loops."

The AI reads your actual code, not generic examples, so the advice matches your specific setup.

Summary

Problem	Most Likely Fix
Nil value errors	Add dependency in fxmanifest, guard player access
Events not firing	Triple-check event name casing and file paths
qb-target not showing	Enable debugPoly, fix start order
Database errors	Validate schema, use json.encode() for objects
Server lag	Add Wait() calls, move registrations to file scope

Having trouble? Check the error reference or ask in the FiveForge Discord.