> 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/interface/cuxial-chat/troubleshooting.md).

# Troubleshooting

Common Cuxial Chat problems, with their cause and fix.

The most frequent problems after installing Cuxial Chat, with the cause and the fix for each one.

<details>

<summary>The resource does not start</summary>

**Cause.** A dependency is missing or starts later than the chat. Cuxial Chat needs OneSync, `ox_lib`, `oxmysql` and `cuxial_bridge`.

**Fix.** Enable OneSync and start the dependencies first:

{% code title="server.cfg" %}

```cfg
ensure ox_lib
ensure oxmysql
ensure cuxial_bridge
ensure cuxial_chat
```

{% endcode %}

</details>

<details>

<summary>Two chats appear, or the default chat still opens</summary>

**Cause.** Another chat resource is still running. Cuxial Chat provides `chat` and cannot share it.

**Fix.** Remove `ensure chat` and any other chat script from `server.cfg`, then restart the server.

</details>

<details>

<summary>Pressing T does nothing and the chat never shows</summary>

**Cause.** The interface is not loading. The folder `web/dist` is missing or incomplete, usually after a partial upload.

**Fix.** Make sure `web/dist/index.html` and the folder `web/dist/assets` exist inside the resource. If they do not, copy the resource again from the original package and restart the server.

</details>

<details>

<summary>I changed ui.openKey but the chat still opens with the old key</summary>

**Cause.** `ui.openKey` is only the default. Once a player has joined, FiveM remembers their key binding.

**Fix.** Each player changes it in the GTA settings, under key bindings for FiveM. New players get the new default.

</details>

<details>

<summary>/me and /do do not appear in the chat</summary>

**Cause.** `actions.display` is `'head'`, so actions are shown only above the head.

**Fix.** Set `actions.display = 'both'` in `shared/config.lua`. Players who already picked a value in their settings keep their own choice.

</details>

<details>

<summary>Player names show as "Player 12"</summary>

**Cause.** The chat could not read the character name. `cuxial_bridge` is not connected to the framework, or it started before it.

**Fix.** Start your framework before `cuxial_bridge`, and `cuxial_bridge` before `cuxial_chat`.

</details>

<details>

<summary>The name is not hidden when wearing a mask</summary>

**Cause.** One of these:

* `anonymous.enabled` is `false`.
* `anonymous.anyMask` is `false` and the mask number is not in `anonymous.masks`.
* The channel is not set to `true` in `anonymous.channels`.
* The message is a private message or goes to the organization channel. Both always show the real name.
* The clothing resource has just changed the mask.

**Fix.** Review the `anonymous` block. To update at once after a clothing change, call `exports.cuxial_chat:refreshMask()` from the client.

</details>

<details>

<summary>/gchat answers "You do not belong to any organization"</summary>

**Cause.** The player has no gang, and their job is not in `gchat.policeJobs` (or they are off duty with `gchat.requireDuty = true`).

**Fix.** Give the player a gang, or add their job type or job name to `gchat.policeJobs`.

</details>

<details>

<summary>All organizations have the same colour in /gchat</summary>

**Cause.** `cuxial_gang` is not running, so every organization uses `gchat.fallbackColor`.

**Fix.** Start `cuxial_gang`, or change `gchat.fallbackColor`. The chat reads the colours again within a minute; no restart is needed.

</details>

<details>

<summary>The image command does not exist or rejects the link</summary>

**Cause.** `images.enabled` is `false` by default. With it enabled, a link is rejected when it is not `https`, it is longer than 400 characters, its domain is not in `images.hosts`, it does not end in an extension from `images.extensions`, or the player went over `images.perMinute`.

**Fix.** Set `images.enabled = true` and add the domains you want to allow. The chat tells the player why a link was rejected.

</details>

<details>

<summary>Settings are lost when the player reconnects</summary>

**Cause.** `persistSettings` is `false`, or the table `cuxial_chat_settings` could not be created.

**Fix.** Set `persistSettings = true` and check the server console for `oxmysql` errors when the resource starts. The database user needs permission to create tables.

</details>

<details>

<summary>Logs do not reach Discord</summary>

**Cause.** The webhook convar is empty or has a different name from `logs.discord.convar`, or the channel is not enabled in `logs.channels`.

**Fix.** Add the convar to `server.cfg` before the chat starts. It is read once, when the resource starts:

{% code title="server.cfg" %}

```cfg
set cuxial_chat_webhook "https://discord.com/api/webhooks/..."
```

{% endcode %}

Messages are sent in batches, so they can take up to `logs.discord.flushMs` to arrive. With `debug = true` the console shows whether Discord is active and any failed response.

</details>

<details>

<summary>Texts appear in the wrong language</summary>

**Cause.** The chat follows the `ox:locale` convar.

**Fix.** Set it in `server.cfg` and restart. `en` and `es` are included:

{% code title="server.cfg" %}

```cfg
setr ox:locale "en"
```

{% endcode %}

</details>

<details>

<summary>Commands from another resource are missing in the autocomplete</summary>

**Cause.** That resource does not announce its commands to the chat.

**Fix.** Add them with the standard event:

```lua
TriggerClientEvent('chat:addSuggestion', -1, '/mycommand', 'What it does')
```

</details>

<details>

<summary>Messages sent too fast are dropped</summary>

**Cause.** For text written without a command, the chat accepts one message every 300 milliseconds per player. Messages are limited to 400 characters. This protects the server from spam.

**Fix.** None needed. It is intended.

</details>


---

# 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/interface/cuxial-chat/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.