> For the complete documentation index, see [llms.txt](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/multichar/troubleshooting.md).

# Troubleshooting & FAQ

{% hint style="info" %}
Start every investigation with `gmc selftest` from the server console: it lists what to fix. Levels: error, warning, info, ok.
{% endhint %}

### Black screen on join

Check F8 and the server console, then run `gmc selftest`. Common causes:

* `oxmysql` not started, or the resource starts before the framework.
* ESX does not see `esx_multicharacter` (see [Installation](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/multichar/installation.md#esx-legacy): the resource stays passive).
* `qb-multicharacter`, `qb-spawn` or `esx_multicharacter` still running.
* Another loadscreen is running (FiveM uses only one).

A watchdog (`Config.Scenes.revealTimeoutMs`, 15 s) clears the black screen anyway; if the scene fails to load, a plain backdrop is shown.

### The mouse cursor does not respond on first join

Fixed in 1.0.1 and 1.0.2 (see the [Changelog](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/multichar/changelog.md)). If you see it on an older version, update.

### A character does not show up

Run `gmc info <target>` and `gmc backup list <target>`. To bring characters over from another script use `gmc import esx|qb|qbox` from the console (without `--apply` it is a dry run). On a server that is already running no existing character is locked by the default; a locked character means staff used `/gmc char lock` or `/gmc slots remove|set`.

### The selection scene looks wrong (missing ped, out of frame)

Set `Config.Scenes.debug = true` and run `/gmc camdebug` in game (chat or F8, no permission). F8 shows the scene, the camera (position, fov, distance, check) and, for every ped, coordinates, `IsEntityOnScreen`, ground and pose, plus the placeholder and the highlight method. With `debug` the discarded spots are printed too. Send those lines to support.

### The appearance creator fails

The player is never left stuck: if saving the appearance fails it is retried 3 times, then the player goes back to the selection with an error message, and the creator restarts on re-entry. Check the adapter with `gmc selftest`.

### Weather and time during selection

See [Integrations](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/multichar/integrations.md#weather-sync). `vSync` cannot be paused cleanly; `cd_easytime` forces `EXTRASUNNY` while paused.

### The pause menu does not open / ESC does nothing

Situations are controlled by `Config.Pause.block`. With `blockedAction = 'ignore'` ESC does nothing while blocked; with `'native'` the GTA menu opens. If detection fails, force `Config.Pause.interceptMode` to `'controls'`, `'frontend'` or `'native'`. A native page (map, settings, keys) that does not open within 1 s disappears from the UI: the hashes are in `Config.Pause.native`.

### Players cannot go back to the selection

Only `/relog` (or the pause menu button) works, and it follows the `Config.Pause.changeCharacter` rules: dead, cuffed, recent damage, in vehicle and the cooldown all block it. The reason is shown in the pause menu. A second `/relog` during the countdown does nothing.

### Qbox: "delete door still open" warning

Follow step 3 of the Qbox installation: remove the two `deleteCharacter` handlers in `qbx_core`. See [Installation](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/multichar/installation.md#qbox).

### Slots: a player has fewer or more slots than expected

Slots are `Config.Slots.default` plus ACE rules, `/gmc slots add` and Tebex grants, up to `Config.Slots.max` (max 15). On a running server an account never has fewer slots than characters. Check with `gmc info <target>`.

### RPC timeout warning in the selftest

`Config.Rpc.clientTimeoutMs` must be at least `Config.ESX.joinTimeoutMs` + 5000.

## Still stuck?

Send the `gmc selftest` output, the framework and the F8 lines to [support](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/support.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://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/multichar/troubleshooting.md?ask=<question>&goal=<user_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.
