> For the complete documentation index, see [llms.txt](https://docs.cuxial.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cuxial.com/scripts/core/cuxial-multichar/troubleshooting.md).
# Troubleshooting
Common problems with Cuxial Multichar and how to fix them.
Most problems come from a missing dependency, the start order or a convar. Check the server console first: the resource reports what is wrong.
The resource does not start
**Cause.** A required dependency is missing or starts later: OneSync, `ox_lib`, `oxmysql` or `cuxial_bridge`.
**Fix.** Enable OneSync and start those resources before `cuxial_multichar`. See the order in [Installation](/scripts/core/cuxial-multichar/installation.md).
The selection opens but no character can be loaded or created
**Cause.** The framework was not detected. Cuxial Multichar requires QBox or QBCore.
**Fix.** Start your framework before `cuxial_bridge`, and `cuxial_bridge` before `cuxial_multichar`.
The character shows the base body or the creator does not open
**Cause.** No supported appearance resource is running. Cuxial Multichar uses `cuxial_appearance` and, if it is not running, `illenium-appearance`. With starting apartments in use, the creator is not opened by this script either.
**Fix.** Start one of the two before `cuxial_multichar`. With `illenium-appearance`, the look comes from the `playerskins` table: the character needs a row with `active = 1`.
Black or empty screen instead of the selection
**Cause.** The `web/build` folder is missing or incomplete, or another loading screen resource is running.
**Fix.** Upload the resource again with its full `web/build` folder and remove any other loading screen from your `server.cfg`.
Discord roles give no extra slots
**Cause.** One of these:
* `discordSlots.enabled` is `false`.
* The convars are missing. The console warns that Discord slots are enabled but the bot or server convars are missing.
* The bot is not in your Discord server, or the token is wrong. The console shows the status code Discord answered with.
* The player has no Discord linked to FiveM.
* The role ID is wrong, or `characters.maxSlots` is lower than the slots of the role.
**Fix.** Check each point. Role changes take up to `discordSlots.cacheMinutes` to apply, or until the player reconnects.
Extra slots disappear from time to time
**Cause.** Discord did not answer within `discordSlots.timeoutMs`. The player gets the base slots, and the request is retried a minute later.
**Fix.** Raise `discordSlots.timeoutMs`. For key users, add them to `discordSlots.users`, which does not depend on Discord answering.
New characters spawn without items
**Cause.** A starter item does not exist in your inventory, or the inventory did not load in time. The console names the item or the player.
**Fix.** Create the items or edit `starterItems` in the config.
The ID card does not appear when creating a character
**Cause.** The resource set in `idCard.resource` is not running, or it has no card for `idCard.item`.
**Fix.** Start that resource before `cuxial_multichar`, or set `idCard.enabled = false`.
The vehicle option is missing in the selection
**Cause.** The resource set in `vehicles.resource` is not running, or the character owns no car or motorcycle.
**Fix.** Start that resource, or set `vehicles.enabled = false` to hide the feature.
Characters stand still without an emote
**Cause.** `cuxial_emotes` is not running. The scene falls back to `scene.fallbackScenario`.
**Fix.** Start `cuxial_emotes`, or use locations with `emote = { scenario = '...' }`.
A minor character cannot be played
**Cause.** The request is still pending, or it was rejected or revoked. Minors need staff approval before the first spawn.
**Fix.** Review the request with the [exports](/scripts/core/cuxial-multichar/developers.md).
No logs arrive in Discord
**Cause.** The `cuxial_multichar_webhook` convar is empty, `logs.enabled` is `false`, or the webhook was deleted. The console shows the status code when the webhook rejects a message.
**Fix.** Set the convar with `set` and restart the resource.
The HUD stays visible in the selection
**Cause.** The `hud` function in the config is empty or fails. A failure is printed in the client console.
**Fix.** Call your HUD's export inside `hud = function(visible) ... end`.
Staff commands answer with no permission
**Cause.** The player is not in the group set in `restricted`.
**Fix.** Add the player to that group with `add_principal`. See [Commands & permissions](/scripts/core/cuxial-multichar/commands.md).
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.cuxial.com/scripts/core/cuxial-multichar/troubleshooting.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.