Debugging QBCore Resources

Reliable debugging keeps your server stable and your players happy. This guide focuses on practical techniques for isolating pr oblems in Lua scripts, network events, and configuration files so you can ship fixes quickly.

Before You Dive In

Reproduce the issue intentionally. Collect the command, player action, or resource load sequence that triggers the bug.
Check for obvious configuration mistakes. Run the Config Validator against any config files yo u touched recently to eliminate syntax and logical errors early.
Review recent changes. Use Git history or pull request diffs to pinpoint suspect resources, dependencies, or manifest ed its.

💡 Keep a running log of steps taken. A simple debug-log.md in your resource helps you and teammates avoid duplicating work.

Logging Fundamentals

Thoughtful logging is still the fastest way to understand runtime behaviour.

Use scoped prefixes. Wrap every print or lib.logger.debug call with the resource name (e.g., [qb-trucking] Loaded r oute table) so you can filter logs quickly.
Prefer structured tables. Serialise Lua tables with json.encode before printing to avoid unreadable output.
Throttle noisy loops. When debugging ticking threads, log on state changes instead of every frame, or use counters to sam ple output once every few seconds.
Mirror client/server logs. For shared events, log on both sides and include the source id to confirm the execution path.

local QBCore = exports['qb-core']:GetCoreObject()
 
RegisterNetEvent('qb-example:server:doThing', function(data)
    local src = source
    QBCore.Functions.Print('[qb-example] received payload', json.encode(data))
 
    if not data or not data.playerId then
        QBCore.Functions.Print('[qb-example] missing playerId, aborting request', 'error')
        return
    end
 
    -- ...rest of your handler
end)

Inspecting Events with the Event Debugger

The Event Debugger offers a real-time view into all client and server events.

Start a capture session for your suspect resource. Use the built-in filters to limit noise by event prefix (e.g., qb-ex ample:).
Trigger the bug in-game and watch the event timeline. Pay attention to missing responses or unexpected parameter values.
Expand the payload viewer to inspect the arguments sent between client and server.
Export the session if you need to share context with collaborators or review offline.

Pair the Event Debugger with targeted logging: when an event is missing, cross-reference the capture with your console logs to s pot handler crashes or early returns.

Validating Configuration and Data

Configuration mistakes frequently cause silent failures. Running the Config Validator is an easy way to catch:

Invalid vehicle or item names referenced in scripts
Typographical errors in locale or permissions tables
Performance traps such as unbounded loop intervals or heavy synchronous database calls inside event handlers

Whenever you migrate to a new QBCore release, validate every resource config before launching to production.

A Repeatable Debugging Workflow

Step	Question to Answer	Helpful Tools
1. Capture context	What changed and who is affected?	Git history, deployment logs
2. Validate inputs	Are configs, locales, and manifests valid?	Config Validator
3. Trace execution	Which events or functions ran?	Event Debugger, targeted logging
4. Inspect data	Are payloads and database records correct?	`json.encode`, database CLI
5. Confirm the fix	Does the bug stay resolved after a restart?	Automated tests, QA checklist

Document each run-through in your issue tracker so others can reuse the playbook next time.