> 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-multicharv3/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.

<details open>

<summary>Resource fails to start</summary>

Check your `server.cfg` and confirm that `ensure cylex_multicharv3` appears **after** your framework line (ESX, QBCore, or QBox) and after your database connector. If the resource loads before its dependencies are ready, it will fail silently or throw errors on startup.Open your server console and look for red error lines near the resource name. These usually point directly to the problem.If the errors aren’t obvious, enable verbose logging by opening `config.lua` and setting:

```lua
Config.Debug = true
```

Restart the resource and check the console again — debug mode prints detailed output at each stage of startup. Turn it back off before going live.

</details>

<details open>

<summary>UI doesn't open when a player connects</summary>

The character select screen is driven by a browser page (`html/index.html`). If that page isn’t loading, the UI won’t appear.

1. Open `fxmanifest.lua` and confirm the line `ui_page "html/index.html"` is present and unchanged. Do not edit this file — if it has been modified, restore it to the original.
2. Join the server, press **F8** to open the in-game browser console, and look for any JavaScript errors. These errors identify which part of the NUI failed to load.
3. If no obvious errors appear, run `restart cylex_multicharv3` in the server console to force a clean reload of the resource.

</details>

<details open>

<summary>Characters not saving or loading</summary>

Cylex Multicharacter requires a database connector to read and write character data. If characters disappear on reconnect or fail to load, check the following:

* Confirm that **oxmysql** or **mysql-async** is running and successfully connected to your database. Look in the server console at startup for any database connection errors.
* If the resource started correctly but characters still aren’t persisting, the framework auto-detection may have picked the wrong value. Open `config.lua` and set `Config.Framework` manually:

```lua
Config.Framework = "qb"   -- or "esx"
```

Restart the resource after making this change.

</details>

<details open>

<summary>Wrong language is showing</summary>

The `Config.DefaultLang` value in `config.lua` must exactly match the filename of a locale file in the `locales/` folder — without the `.lua` extension.For example, if you want English, confirm:

```lua
Config.DefaultLang = "en"
```

and that `locales/en.lua` exists. If you set `Config.DefaultLang = "EN"` (uppercase) or `Config.DefaultLang = "english"`, the script won’t find the file and will fall back silently.Players can change their own language from the in-game Settings menu inside the character select screen. Their saved preference overrides the server default — so a player may see a different language than you expect even after you update `Config.DefaultLang`.

</details>

<details open>

<summary>Weather or time on the character screen is wrong</summary>

If the weather or time of day on the character select screen doesn’t match what you configured, there are two likely causes.First, check that `Config.Environment.DefaultWeather` in `config.lua` is set to a valid uppercase weather string. Valid values include `CLEAR`, `EXTRASUNNY`, `CLOUDS`, `OVERCAST`, `RAIN`, `THUNDER`, `CLEARING`, `SMOG`, `FOGGY`, `XMAS`, `SNOWLIGHT`, `BLIZZARD`, and `NEUTRAL`. Any other string will be ignored.Second, if you have a third-party weather or time sync script running (such as `qb-weathersync` or `cd_easytime`), it may be overriding Cylex’s values after they are set. Update the `DisableThirdPartySync` function in `config.lua` to trigger the correct pause event for your specific script:

```lua
DisableThirdPartySync = function()
    TriggerEvent('qb-weathersync:client:DisableSync')
    TriggerEvent('cd_easytime:PauseSync', true)
end,
```

Replace the event names with whatever your weather script uses. If you don’t have a third-party sync script, set the function body to `function() end`.

</details>

<details open>

<summary>Partner system isn't working</summary>

The partner system requires both players to be on the character select screen at the same time. If one player has already loaded into the world, the pairing request cannot be completed.If both players are on the screen but the feature still doesn’t work, open `shared/animations.lua` and confirm:

```lua
Config.Partner = {
    enabled = true,
    ...
}
```

If `enabled` is set to `false`, the partner UI will not appear for any player.Also note that each player can only have one active partner at a time. If a player is already paired, they must open the Partner tab and click **Unpair** before they can send or accept a new request.

</details>

<details open>

<summary>Discord webhooks not sending</summary>

If character events are not posting to your Discord channel, work through these checks:

1. Open `shared/webhooks.lua` and confirm you replaced every `"YOUR_WEBHOOK_URL"` placeholder with a real Discord webhook URL.
2. Verify the webhook URL is still valid — if the Discord channel was deleted or the webhook was regenerated, the old URL will return an error.
3. Check the server console for lines beginning with `[Cylex Webhooks] HTTP` — these lines log the HTTP status code returned by Discord and will tell you if the request is reaching Discord but being rejected (for example, a 404 means the channel or webhook no longer exists).

Never share your webhook URLs publicly. Anyone with the URL can post messages to that Discord channel.

</details>

<details open>

<summary>Spawn selector not appearing or wrong script detected</summary>

When `Config.SpawnSelector = "Auto"`, the resource tries to detect which spawn script you have installed. If detection fails or picks the wrong script, set the value manually in `config.lua`:

```lua
Config.SpawnSelector = "qs-spawn"   -- or "cd-spawn", "qb-spawn", "renzu-spawn", "builtin"
```

If your spawn script is not in the supported list, set it to `"custom"` and implement your own handler in `shared/bridge/spawn_selector.lua`. That file is open and fully documented.To skip the selector entirely and always spawn at the player’s last saved location, set:

```lua
Config.SpawnSelector = false
```

</details>

### [​](https://cylex.mintlify.app/troubleshooting#still-stuck)Still stuck? <a href="#still-stuck" id="still-stuck"></a>

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.