How to read a FiveM SCRIPT ERROR: file, line and stack trace

A typical error in the console:

SCRIPT ERROR: @my_script/server/main.lua:42: attempt to index a nil value (local 'xPlayer')
> handler (@my_script/server/main.lua:42)
> ref (citizen:/scripting/lua/scheduler.lua:...)

It looks like noise, but every part has a meaning, and it usually tells you exactly where to look. This guide shows how to read it, where to find it, and what to do when it is not enough.

#The first line: what, where and why

SCRIPT ERROR: @my_script/server/main.lua:42: attempt to index a nil value (local 'xPlayer')

• SCRIPT ERROR: marks a Lua error in a script. The script keeps running after it, but the code that failed stopped at that line.
• @my_script/server/main.lua is the resource name (my_script) and the path of the file inside the resource folder.
• :42 is the line number in that file.
• The rest is the message: attempt to index a nil value (local 'xPlayer'). Lua reads it like this: on line 42 you tried to use something inside xPlayer, but xPlayer is nil.

Open the file, go to that line, and look at the variables that line uses. In most cases the answer is already there. Common messages have their own guides: attempt to call a nil value and attempt to compare nil.

#The stack trace: how the code got there

The lines starting with > are the stack trace. It lists the functions that were running, from the failing one down to the one that started it:

> handler (@my_script/server/main.lua:42)
> ref (citizen:/scripting/lua/scheduler.lua:...)

The first line after the error is the same place as the error. Lines below it show who called that function. When the error is inside a library or another resource, a line from your own script further down the list is often the real cause, because your script passed a wrong value into it.

Lines that begin with citizen:/scripting/lua/... (for example citizen:/scripting/lua/scheduler.lua) belong to FiveM itself. They are part of the machinery that runs your events and threads. You can ignore them: the error is never fixed there, and they only show that a thread or an event was running.

#Client or server: where to look

A script error appears on the side where the code runs:

• Client scripts (client_scripts, files in a client folder): press F8 in game to open the client console. If you do not see anything, scroll up, as errors can scroll away fast.
• Server scripts (server_scripts, files in a server folder): read the server console. In txAdmin, that is the Live Console page. On a server started from a terminal, it is that terminal window.
• Shared scripts run on both sides, so the error can show up in either place.

Tip: if a menu or an action does nothing and F8 is empty, check the server console. The failing code may be on the server side.

#Which line to look at

1. Read the message first: it says what kind of problem it is (nil, a wrong type, a missing export).
2. Open the file and line from the first line. Check every variable on it.
3. If the file belongs to a library (ox_lib, the framework), go down the stack trace until you reach a line of the script you are fixing.
4. Check if the error appears once or constantly. A constant error in a loop floods the console. Fix that one first, as it hides other messages.

Errors with the text No such export or could not find dependency are different. They are about resources, not lines of code. See could not find dependency.

#When the line is not enough: add prints

If the line uses several variables and you do not know which one is nil, print them just before it:

print('xPlayer:', xPlayer)
print('source:', source, type(source))
print('data:', json.encode(data))

Run the code again and read the console. Some tips for useful prints:

• Print the type as well as the value: type(value) shows nil, number, string, table or function.
• Use json.encode(table) to see the inside of a table. A plain print(table) only shows a memory address.
• Put a short label in front, so you can find the line in a busy console.
• Print at the start of a function, to confirm it runs at all.

Remove the prints once the problem is fixed, as they cost performance in busy loops.

#Where an error does not appear

• Escrowed scripts hide their code. The error gives you a file name, but the file is encrypted and you cannot read the line. Contact the author with the full error text.
• NUI errors (the menu itself, written in HTML and JavaScript) do not show in F8 as SCRIPT ERROR. Open the NUI developer tools to read them: the nui_devtools command in the F8 console opens them in a browser tab.
• Errors in the first seconds: when you start the server, errors from resources that fail to load can pass quickly. Search the console or scroll back up, or restart only the one resource and watch.

#What to send when you ask for help

Copy the complete error, the stack trace included, as text, and say whether it comes from F8 or from the server console. Add the line of code it points to and the framework you use. A screenshot of one cropped line is not enough for anyone to help you.

#Checklist