> For the complete documentation index, see [llms.txt](https://cylexdev.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cylexdev.gitbook.io/docs/cylex_mdt/troubleshooting-common-issues.md).
# Troubleshooting Common Issues
Fix the most common Cylex Multicharacter problems — startup failures, UI not opening, characters not saving, webhook errors, and more.
If something isn’t working as expected, this page walks you through the most common issues and how to resolve them. Start with the section that best describes your symptom, work through each step in order, and restart your server after making any config changes.
I want to disable Forensic (Bullet, Blood evidence)
`cylex_mdt/editable/evidence_config.lua`
```lua
EvidenceConfig = {}
EvidenceConfig.Enabled = {
blood = true, -- Blood Evidence
casing = true, -- Bullet Casing Evidence
}
```
#### Options
* `blood`\
Enables or disables blood evidence generation.
* `casing`\
Enables or disables bullet casing evidence generation.
Set any option to `false` to disable that evidence type.
**Example:**
```lua
EvidenceConfig.Enabled = {
blood = false,
casing = true,
}
```
This disables blood evidence while keeping bullet casing evidence enabled.
{% hint style="warning" %}
[We recommend disabling this on servers with 200–300+ players.](#user-content-fn-1)[^1]
{% endhint %}
"Framework not detected" in the console
The auto-detection scan did not find `qbx_core`, `qb-core`, or `es_extended` in the list of started resources. Set the framework manually in `editable/config.lua`:
```lua
Config.Framework = 'qb' -- QBCore or QBX
-- or
Config.Framework = 'esx' -- ESX
-- or
Config.Framework = 'custom' -- custom bridge
```
See [Framework and inventory compatibility](https://cylex-137e2d97.mintlify.app/frameworks) for custom bridge setup.
MDT won't open
The resource enforces a job allowlist before opening the MDT. Check the health-check output printed to the server console on startup — it will flag if `Config.AllowedJobs` is empty or if the player's current job is not in the list.
```lua
-- editable/config.lua
Config.AllowedJobs = {
['police'] = true,
['sheriff'] = true,
}
Config.Departments = {
{ id = 'police', name = 'MRPD', fullName = 'Mission Row Police Department', jobName = 'police', color = '#043052', logo = 'police.png' },
{ id = 'sheriff', name = 'BCSO', fullName = 'Paleto Bay Sheriff Office', jobName = 'sheriff', color = '#d47a20', logo = 'sheriff.png' },
}
```
{% hint style="info" %}
Ensure the job name matches exactly what your framework returns for the player (case-sensitive). Also confirm that the player is on duty — the MDT blocks access for off-duty officers by design.
{% endhint %}
Need to add a new language
The MDT ships with English (`en`) and Turkish (`tr`). To add another language:
1. Copy `editable/locales/en.lua` to `editable/locales/xx.lua`, replacing `xx` with your language code (e.g. `de` for German).
2. Change `Locales['en']` at the top of the new file to `Locales['xx']`.
3. Translate all string values in the file. Do not change the keys.
4. Translate the `dataMap` block — this covers statuses, priorities, and felony class names pulled from the database.
5. Set `Config.Locale = 'xx'` in `editable/config.lua`.
6. Restart the resource with `ensure cylex_mdt`.
Database errors on startup
The MDT requires a database driver to be running before it starts. Supported drivers are `oxmysql`, `ghmattimysql`, and `mysql-async`. Make sure the driver resource is listed in your `server.cfg` **before** `cylex_mdt`:
```lua
# server.cfg
ensure oxmysql
ensure cylex_mdt
```
Also confirm that `Config.Database` in `editable/config.lua` matches the driver you are using:
```lua
-- editable/config.lua
Config.Database = 'oxmysql' -- 'oxmysql' | 'ghmattimysql' | 'mysql-async'
```
I can open MDT without tablet item / I want to open MDT with command without item
If you set `Config.TabletItem` to `"tablet`" instead of false, you won't be able to use the item without selecting it, whether via a command, a key, or while using the item itself.
You can either disable opening via a key by setting `Config.OpenKey` to `false`, prevent opening via a command by setting `Config.OpenCommand` to `false`, or set `Config.TabletItem` to `false`.
```lua
-- editable/config.lua
Config.OpenKey = 'F5' -- Key to open MDT or set false to disable to open with key
Config.OpenCommand = 'mdt' -- Open with /mdt command or set false for disable
Config.UniformPopupKey = 'J' -- Hold key to show mouse cursor on the floating uniform popup (LMENU = Left Alt)
Config.TabletItem = false -- Inventory item that opens the MDT when used. Set to '' or false to disable. Job permission is still enforced.
```
{% hint style="info" %}
Note that the job allowlist (`Config.AllowedJobs`) is still enforced even when on all types & `Config.TabletItem` is `false`.
{% endhint %}
Officers can't see or collect evidence in the field
Two settings control field evidence collection:
**Flashlight mode** — By default, officers must hold `weapon_flashlight` and right-click (aim) to illuminate nearby evidence markers. If officers report they cannot see evidence, confirm they have a flashlight equipped and are aiming it.
**Collect jobs** — The `EvidenceConfig.CanCollectJobs` list in the evidence configuration controls which jobs are allowed to collect evidence from the scene. Make sure the officer's job is included.
Check the server console for `[MDT]` evidence-related messages, which will indicate if a permission or proximity check failed.
Evidence stash not showing
If the evidence drop-off stash does not appear at the expected location, check that the coordinates defined in `EvidenceConfig.Stashes` match the actual positions on your server's map. Coordinate values that are correct for a vanilla GTA V map may be off if your server uses a custom or modified map.
Only seeing your own department's data
`Config.DepartmentScopedData` is set to `true` by default. When enabled, Units, Radio Codes, Templates, FTO reports, and Exams pages only show records belonging to the player's own department.
```lua
-- editable/config.lua
Config.DepartmentScopedData = true
```
I don't want police officers to be able to make changes on the "Permissions" page. How can I do that?
The Permissions page visibility is controlled by `Config.PermissionsPageAccess`:
```lua
-- editable/config.lua
Config.PermissionsPageAccess = 'admin' -- 'boss' | 'admin'
```
* `'boss'` — only the job's boss-grade officers can see and access the page
* `'admin'` — only players with server admin ACE permissions can see and access the page
If you are a server admin but still cannot see the page, also confirm that `Config.EnabledPages['permissions']` is set to `true`.
### [](https://cylex.mintlify.app/troubleshooting#still-stuck)Still stuck?
If none of the above resolved your issue, open a support ticket in the [**Cylex Discord**](https://discord.gg/cylexstore) server. To get help as quickly as possible, include all of the following in your ticket:
* Your framework (ESX, QBCore, or QBox) and its version number
* Full error messages from the server console — paste the text or attach a screenshot
* A description of what you changed in the config files
* The exact steps needed to reproduce the problem
Support does not cover issues caused by editing escrow-protected files in `client/` or `server/`, unsupported changes to `html/js/index.js`, or conflicts introduced by other scripts that modify the same game systems.
[^1]: