Debugging FiveM resources

Most FiveM bugs are found in minutes if you know where to look. This page is the routine: where errors show up, how to read them, how to narrow down a bug, and the errors you’ll see most.

Where output goes

Keep the F8 console and the Live Console open side by side while you test.

Reading a script error

SCRIPT ERROR: @my_shop/server/main.lua:42: attempt to perform arithmetic on a nil value (local 'price')
> handler (@my_shop/server/main.lua:42)
> fn (@ox_lib/imports/callback/server.lua:28)

• @my_shop/server/main.lua:42: resource, file, line. Go there first.
• attempt to perform arithmetic on a nil value (local 'price'): what went wrong and which variable. price is nil on line 42.
• The lines starting with > are the stack trace: how the code got there. Here an ox_lib callback called our handler.

Now ask: why is price nil? Usually a table lookup with a key that doesn’t exist (Config.Prices[item] with a typo in item), or an argument the other side didn’t send.

Print debugging

Plain print is still the most used tool:

print('buy called', src, item, amount)
print(json.encode(data, { indent = true }))   -- dump a table

• json.encode turns tables into readable text. print(someTable) alone prints only table: 0x....
• ox_lib has lib.print.info(...), lib.print.debug(...) with log levels you can switch with a convar (ox:printlevel).
• Prefix your prints with the resource or function name so you can find them among other output.
• Remove debug prints (or put them behind a Config.Debug flag) before release. Spamming the console costs performance.

A debugging routine

1. Reproduce it. Find the exact steps that trigger the bug.
2. Read the first error, not the last. Later errors are often side effects.
3. Check which side the problem is on: does the server get the event? Put a print at the top of the server handler. Does the client get the reply? Print in the client handler.
4. Check the inputs: print the arguments at the start of the function. Half of all bugs are “the value wasn’t what I thought”.
5. Cut it in half: comment out half of the suspicious code, see if the bug stays, repeat.
6. Restart just your resource (ensure name) instead of the whole server, it’s faster. But if things behave oddly after many restarts, restart the server: some resources don’t clean up on stop.
7. Check the load order: framework not started yet, dependency missing, ensure order in server.cfg.
8. Change one thing at a time, then test.

The errors you’ll see most

Client debugging tools

• F8 console commands: resmon 1 (resource CPU and memory), netgraph (network graph), cl_drawfps true, profiler record (see Threads and performance).
• nui_devtools: Chrome DevTools for NUI. Your JavaScript errors and console.log appear there.
• Draw it: draw a marker or text at the coordinates your code uses, to see where it thinks things are.
• Coordinates: print GetEntityCoords(PlayerPedId()) and GetEntityHeading(PlayerPedId()) to grab positions for configs, or pick them on the Interactive Map.

Server debugging tools

• The txAdmin Live Console with search, and the log files in txData.
• status lists players and their IDs.
• mysql_debug and mysql_slow_query_warning convars for oxmysql.
• The server profiler (profiler record 500 in the server console, then profiler saveJSON file.json) for slow ticks. Drop the file into the Profiler Analyzer to see which resources use the most time.
• txAdmin’s performance chart for hitches over time.

Debugging streamed assets

• Missing model or texture: check the file is in stream/, the name matches exactly (case matters on Linux), and the resource is started. The Vehicle Pack Validator checks a vehicle resource for broken links between metas, stream files and the manifest.
• A data_file path that doesn’t match a file listed in files is silently ignored.
• Oversized asset warnings in the server console point to textures that need shrinking.

More in Streaming custom assets.

Tools that make debugging easier

• The Lua Language Server in VS Code flags undefined globals and wrong argument counts before you run the code. See Start developing.
• Git: git diff shows exactly what changed since it last worked. git stash lets you test the old version in seconds.

Asking for help

When you’re stuck, a good question gets an answer fast:

• What you’re trying to do, in one sentence.
• The exact error text (copied, not a phone photo of the screen).
• The relevant code, formatted, with line numbers matching the error.
• What you already tried.
• Artifact build, framework and version.

Post it on forum.cfx.re in the Development category or in the framework’s Discord support channel.

Next: Streaming custom assets.