Framework Errors

This guide covers common errors related to FiveM frameworks like ESX and QBCore, and how to resolve them.

ESX Framework Errors

1. ESX Not Found

-- Error: ESX object not found

Solutions:

Ensure ESX is properly installed
Check resource loading order
Verify ESX initialization:

ESX = exports['es_extended']:getSharedObject()

2. Player Data Issues

-- Error: Player data not loaded

Solutions:

Wait for player data to load:

ESX.RegisterServerCallback('resource:callback', function(source, cb)
    local xPlayer = ESX.GetPlayerFromId(source)
    if not xPlayer then
        cb(false)
        return
    end
    -- Your code here
end)

Check player job and inventory:

local xPlayer = ESX.GetPlayerFromId(source)
if xPlayer.job.name ~= 'police' then
    return
end

QBCore Framework Errors

1. QBCore Not Found

-- Error: QBCore object not found

Solutions:

Ensure QBCore is properly installed
Check resource loading order
Verify QBCore initialization:

QBCore = exports['qb-core']:GetCoreObject()

2. Player Data Issues

-- Error: Player data not loaded

Solutions:

Wait for player data to load:

QBCore.Functions.CreateCallback('resource:callback', function(source, cb)
    local Player = QBCore.Functions.GetPlayer(source)
    if not Player then
        cb(false)
        return
    end
    -- Your code here
end)

Check player job and inventory:

local Player = QBCore.Functions.GetPlayer(source)
if Player.PlayerData.job.name ~= 'police' then
    return
end

Common Framework Issues

1. Resource Dependencies

-- Error: Framework resource not found

Solutions:

Add proper dependencies:

dependencies {
    'es_extended', -- For ESX
    'qb-core'      -- For QBCore
}

Check resource loading order in server.cfg

2. Database Integration

-- Error: Failed to save player data

Solutions:

Use framework-specific functions:

-- ESX
xPlayer.setMoney(amount)
 
-- QBCore
Player.Functions.SetMoney('cash', amount)

Implement proper error handling:

local success, error = pcall(function()
    -- Database operation
end)

Best Practices

1. Framework Detection

local framework = 'none'
if GetResourceState('es_extended') == 'started' then
    framework = 'esx'
elseif GetResourceState('qb-core') == 'started' then
    framework = 'qb'
end

2. Error Handling

local function GetPlayer(source)
    if framework == 'esx' then
        return ESX.GetPlayerFromId(source)
    elseif framework == 'qb' then
        return QBCore.Functions.GetPlayer(source)
    end
    return nil
end

3. Resource Structure

resource_name/
├── fxmanifest.lua
├── config.lua
├── client/
│   ├── esx.lua
│   ├── qb.lua
│   └── main.lua
└── server/
    ├── esx.lua
    ├── qb.lua
    └── main.lua

Framework-Specific Issues

ESX Specific Issues

1. ESX Identity Issues

-- Error: Failed to load player identity

Solutions:

Ensure esx_identity is properly configured
Check database table structure
Use the correct event handling:

RegisterNetEvent('esx:playerLoaded')
AddEventHandler('esx:playerLoaded', function(xPlayer)
    local identifier = xPlayer.identifier
    
    MySQL.Async.fetchAll('SELECT * FROM users WHERE identifier = @identifier', {
        ['@identifier'] = identifier
    }, function(result)
        if result[1] then
            -- Identity data is available
            local identity = result[1]
            -- Process identity data
        end
    end)
end)

2. ESX Job Integration

-- Error: Invalid job grade

Solutions:

Ensure job grades are properly defined in the database
Check job assignment logic:

-- Check if job grade exists
local function isValidJobGrade(job, grade)
    local result = MySQL.Sync.fetchAll('SELECT * FROM job_grades WHERE job_name = @job AND grade = @grade', {
        ['@job'] = job,
        ['@grade'] = grade
    })
    return #result > 0
end
 
-- Use in job assignment
if isValidJobGrade('police', 3) then
    xPlayer.setJob('police', 3)
else
    print('Invalid job grade')
end

QBCore Specific Issues

1. QBCore Player Loading

-- Error: Player not loaded

Solutions:

Wait for the correct event:

RegisterNetEvent('QBCore:Client:OnPlayerLoaded')
AddEventHandler('QBCore:Client:OnPlayerLoaded', function()
    local PlayerData = QBCore.Functions.GetPlayerData()
    -- Player is now loaded
end)

Handle player unloading:

RegisterNetEvent('QBCore:Client:OnPlayerUnload')
AddEventHandler('QBCore:Client:OnPlayerUnload', function()
    -- Clean up resources when player unloads
end)

2. QBCore Item Issues

-- Error: Item not found

Solutions:

Check item registration:

-- Server-side
local function hasItem(source, item, amount)
    local Player = QBCore.Functions.GetPlayer(source)
    if not Player then return false end
    
    local playerItem = Player.Functions.GetItemByName(item)
    if not playerItem then return false end
    
    return playerItem.amount >= amount
end

Verify shared items configuration:

-- Check QBShared items
if QBCore.Shared.Items[itemName] then
    -- Item exists
else
    print('Item not registered:', itemName)
end

Cross-Framework Compatibility

1. Framework Wrapper

-- Create a framework wrapper for compatibility
local Framework = {}
 
-- Initialize based on detected framework
local function InitializeFramework()
    if GetResourceState('es_extended') == 'started' then
        ESX = exports['es_extended']:getSharedObject()
        Framework.type = 'esx'
        Framework.getPlayer = function(source)
            return ESX.GetPlayerFromId(source)
        end
        Framework.getMoney = function(player)
            return player.getMoney()
        end
        Framework.setMoney = function(player, amount)
            player.setMoney(amount)
        end
        return true
    elseif GetResourceState('qb-core') == 'started' then
        QBCore = exports['qb-core']:GetCoreObject()
        Framework.type = 'qb'
        Framework.getPlayer = function(source)
            return QBCore.Functions.GetPlayer(source)
        end
        Framework.getMoney = function(player)
            return player.PlayerData.money.cash
        end
        Framework.setMoney = function(player, amount)
            player.Functions.SetMoney('cash', amount)
        end
        return true
    end
    return false
end
 
-- Usage example
if InitializeFramework() then
    RegisterCommand('givemoney', function(source, args)
        local player = Framework.getPlayer(source)
        if player then
            local amount = tonumber(args[1]) or 0
            Framework.setMoney(player, Framework.getMoney(player) + amount)
        end
    end, false)
else
    print('No supported framework detected')
end

2. Framework Detection in Resources

-- Auto-detect framework in fxmanifest.lua
fx_version 'cerulean'
game 'gta5'
 
author 'Your Name'
description 'Cross-Framework Resource'
version '1.0.0'
 
shared_script 'config.lua'
client_scripts {
    'framework/client.lua', -- Framework detection script
    'client/*.lua'
}
server_scripts {
    'framework/server.lua', -- Framework detection script
    'server/*.lua'
}
 
-- Include potential dependencies for auto-detection
dependencies {
    'es_extended',
    'qb-core'
}

Additional Resources

Always test your resource with the specific framework version you're targeting. Framework APIs can change between versions.

For more information about resource loading, check out our Resource Loading Guide.

Framework Errors

On this page