How to Fix "attempt to index a nil value" in FiveM Lua

"attempt to index a nil value" is the single most common error you will see while building GTA roleplay scripts on FiveM. It looks scary, but it always means the same thing: your code tried to read a field (like ESX.GetPlayerData or Config.Jobs) on something that does not exist yet. Lua calls that "something" nil, and you cannot reach into nil. The error message even tells you the variable name in parentheses, which is the fastest clue you have.

This guide breaks down how to read the message, the handful of real causes behind it (an uninitialized framework, a typo, a missing Config, or a player who disconnected mid-script), and the exact fix for each. PlayDeck teaches this kind of debugging with an AI build workflow where you describe the bug, the AI proposes a fix, and you stay in control of the final Lua, so you learn the pattern instead of guessing.

Read the error: the word in parentheses is your suspect

A full FiveM error looks like this: SCRIPT ERROR: @my_resource/server/main.lua:42: attempt to index a nil value (global 'ESX'). Three pieces matter. The file and line (main.lua:42) tell you exactly where to look. The phrase in parentheses tells you what was nil. And the word before it, global, local, field, or upvalue, tells you where that value should have come from.

If it says (global 'ESX') or (global 'QBCore'), your framework object was never assigned, or it was assigned but had not loaded yet when this line ran. If it says (field 'GetPlayerData'), then the thing to the left of the dot was fine but the field after it does not exist. If it says (local 'xPlayer') or (local 'Player'), a variable you fetched earlier came back nil, usually because that player ID was invalid or the player disconnected.

• global 'X' -> X was never set, or set too early in the load order
• field 'Y' -> the object exists, but it has no field named Y (often a typo or wrong API)
• local 'z' / upvalue 'z' -> a fetch above this line returned nil; check that line, not this one
• Always open the exact file:line in the message before changing anything

Cause 1: the framework object loaded too late (ESX / QBCore)

The classic case. Old tutorials told you to grab ESX with TriggerEvent('esx:getSharedObject', function(obj) ESX = obj end). On modern ESX (1.9+) and QBCore that pattern is deprecated and the object can be nil the moment your script runs, so the first ESX.something call throws.

For ESX, fetch the object directly with an export: ESX = exports['es_extended']:getSharedObject(). For QBCore, use QBCore = exports['qb-core']:GetCoreObject(). These return the object synchronously, so it is ready before your next line. Make sure es_extended or qb-core is actually started before your resource (see the dependency guide below), or the export itself will be nil.

If a value still needs time to populate (for example player data right at server boot), wrap the access in a wait loop so you do not index nil: while ESX == nil do Wait(100) end. Used sparingly at the top of a thread, this guarantees the object exists before you touch it.

Cause 2: a nil Config, a typo, or a missing table key

If the nil is something like Config or a key inside it, the usual culprit is load order inside your own resource. In fxmanifest.lua, shared_scripts must list config.lua before any file that reads Config. If config.lua is loaded after server/main.lua, then Config is nil when main runs.

A field error like (field 'Salary') often means you typed Config.Jobs[name].Salary but that job, or that key, was never defined in the config. Print the table to confirm: print(json.encode(Config.Jobs[name])). If it prints nil or is missing the key, the data is the problem, not your logic.

Typos are sneaky because Lua does not warn you. Cfg.Jobs is nil if the table is actually called Config. Tools that lint your Lua, and an AI that reads the whole file at once, catch these instantly, which is part of how PlayDeck's workflow speeds up the loop.

Cause 3: the player disconnected mid-script (local 'xPlayer')

On servers, a very common version is (local 'xPlayer') or (local 'Player') inside a SetTimeout, a delayed callback, or a long loop. The pattern: you fetch the player when an action starts (mining, a sale, a treatment), then several seconds later the callback fires, but the player already left. ESX.GetPlayerFromId now returns nil, and the next xPlayer.addMoney crashes.

Fix it with a guard. Re-fetch the player inside the delayed callback and bail if they are gone: local xPlayer = ESX.GetPlayerFromId(src); if not xPlayer then return end. This single check prevents the crash and is a habit worth building into every server-side callback that touches a player after a delay.

The deeper lesson: never assume a value you fetched earlier is still valid later. Validate at the point of use. Guarding nil before you index it is the difference between a clean log and a server that throws errors every time someone logs out at the wrong moment.