# 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

1. **Reproduce the issue intentionally.** Collect the command, player action, or resource load sequence that triggers the bug.
2. **Check for obvious configuration mistakes.** Run the [Config Validator](/tools/config-validator) against any config files yo
u touched recently to eliminate syntax and logical errors early.
3. **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.

```lua
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](/tools/event-debugger) offers a real-time view into all client and server events.

1. **Start a capture session** for your suspect resource. Use the built-in filters to limit noise by event prefix (e.g., `qb-ex
ample:`).
2. **Trigger the bug** in-game and watch the event timeline. Pay attention to missing responses or unexpected parameter values.
3. **Expand the payload viewer** to inspect the arguments sent between client and server.
4. **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](/tools/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](/tools/config-validator) |
| 3. Trace execution | Which events or functions ran? | [Event Debugger](/tools/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.

## See Also

- [Development Best Practices](/docs/development/best-practices) for coding standards and teamwork habits that prevent bugs.
- [Performance Tuning](/docs/development/performance) to make sure your fixes do not introduce latency or frame drops.
- [VS Code Setup](/docs/development/vscode-setup) for tooling that surfaces errors directly in your editor.
