# Debugging

koja-lib includes a debug printer with coloured log levels.

***

## Config.Debug

Enable debug output globally:

```lua
-- editable/shared/config.lua
Config.Debug = true
```

When enabled, internal koja-lib messages are printed to the console (points callbacks, DUI lifecycle, storage events, etc.).

***

## KOJA.Client.Print

Print a formatted debug message to the client console.

```lua
KOJA.Client.Print(level, debug, message)
```

| Parameter | Type      | Description                                        |
| --------- | --------- | -------------------------------------------------- |
| `level`   | `string`  | Log level — see table below                        |
| `debug`   | `boolean` | If `false`, the message is suppressed              |
| `message` | `any`     | String or table to print (tables are JSON-encoded) |

### Log Levels

| Level       | Colour | Use Case                       |
| ----------- | ------ | ------------------------------ |
| `"success"` | Green  | Successful operations          |
| `"error"`   | Red    | Errors and failures            |
| `"warn"`    | Yellow | Warnings and unexpected states |
| `"info"`    | Blue   | Informational messages         |
| `"debug"`   | Cyan   | Verbose debug output           |

***

## Examples

```lua
KOJA.Client.Print('info', Config.Debug, 'Player loaded')

KOJA.Client.Print('success', Config.Debug, 'Item added successfully')

KOJA.Client.Print('error', Config.Debug, 'Failed to fetch player data')

KOJA.Client.Print('warn', Config.Debug, 'Inventory adapter not found, using fallback')

-- Print a table (auto JSON-encoded)
KOJA.Client.Print('debug', Config.Debug, { job = 'police', grade = 2 })
```

### Gate behind Config.Debug

Pass `Config.Debug` as the second argument so messages only print when debugging is on:

```lua
KOJA.Client.Print('info', Config.Debug, 'Adapter resolved: ' .. KOJA.Inventory)
```

Pass `true` directly to always print regardless of the config:

```lua
KOJA.Client.Print('error', true, 'Critical failure — always shown')
```

***

## Console Output Format

```
^2[SUCCESS]  ^7  Item added successfully
^1[ERROR]    ^7  Failed to fetch player data
^3[WARN]     ^7  Inventory adapter not found, using fallback
^4[INFO]     ^7  Player loaded
^6[DEBUG]    ^7  {"job":"police","grade":2}
```

Colours use FiveM's `^n` colour codes and render in the F8 console.

## Related pages

- [Getting Started](/koja-lib/getting-started) — Configuration and Installation for Getting Started.
- [API Reference](/koja-lib/api-reference) — Client API and Server API for API Reference.
- [Frameworks](/koja-lib/frameworks) — Custom Framework and Overview for Frameworks.
- [Inventory](/koja-lib/inventory) — Custom Inventory and Overview for Inventory.
- [Weapon](/koja-lib/weapon) — Utility function for reading the player's current weapon state.
- [Text UI](/koja-lib/text-ui) — A small on-screen prompt that shows an action key and a label.