> 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-admin/troubleshooting.md).

# Troubleshooting

Common Cuxial Admin problems, with their cause and fix.

The most frequent problems after installing Cuxial Admin, with the cause and the fix for each one. Console messages are quoted as the resource prints them.

<details>

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

**Cause.** A dependency is missing or starts later than the panel. Cuxial Admin needs `ox_lib`, `oxmysql`, `cuxial_bridge` and `qbx_core`. It does not run on QBCore or ESX.

**Fix.** Start the dependencies first:

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

```cfg
ensure ox_lib
ensure oxmysql
ensure qbx_core
ensure cuxial_bridge
ensure cuxial_admin
```

{% endcode %}

</details>

<details>

<summary>The console shows "CONSULTA FALLIDA" when the resource starts</summary>

**Cause.** The tables do not exist. The resource does not create them.

**Fix.** Import `install/cuxial_admin.sql` and restart the resource. The lines under the message show the query and the reason given by the database.

</details>

<details>

<summary>/admin answers that I am not part of the staff</summary>

**Cause.** One of these:

* There is no row for you in `cuxial_admin_staff`.
* The row uses `scope = 'discord'` and you do not have Discord linked to FiveM.
* The row was added while the server was running and has not been loaded yet.
* The row points to a rank that does not exist. The console then shows a warning ending in "apuntan a un rango o ámbito que no existe".
* You have not loaded a character yet.

**Fix.** Check the row, link Discord, and type `staffreload` in the server console. See [Installation](/scripts/core/cuxial-admin/installation.md).

</details>

<details>

<summary>The cursor appears but the panel does not</summary>

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

**Fix.** Copy the resource again from the original package and restart the server.

</details>

<details>

<summary>I changed a key in the config but the old one still works</summary>

**Cause.** `keybinds` only sets the default. Once a player has joined, FiveM remembers their binding.

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

</details>

<details>

<summary>The interface is in one language and the notifications in another</summary>

**Cause.** There are two settings. The interface follows `locale` in `shared/config.lua`. Notifications and key names follow the `ox:locale` convar.

**Fix.** Set both to the same language. `en` and `es` are included:

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

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

{% endcode %}

</details>

<details>

<summary>I want the permission names in another language</summary>

**Cause.** Permission names come from the `label` fields in `data/permissions.lua`.

**Fix.** Translate the `label` fields in `data/permissions.lua`. Rank names are edited from the panel.

</details>

<details>

<summary>The screen view is not available</summary>

**Cause.** One of these:

* `cuxial_admin_screen_owners` is empty. The console shows a warning about it when the resource starts.
* Your Discord ID is not in that list.
* Your rank lacks `player.screen`.
* The convar was changed without restarting the resource.

**Fix.** Add your Discord ID to the convar and restart the resource:

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

```cfg
set cuxial_admin_screen_owners "DISCORD_ID_1,DISCORD_ID_2"
```

{% endcode %}

</details>

<details>

<summary>The screen view works in game but not from the web panel</summary>

**Cause.** Outside the game the video can only arrive through the relay, and the relay is not configured or its values are rejected.

**Fix.** Set both convars. The address must start with `ws://` or `wss://`, and the key must be exactly 64 lowercase hexadecimal characters:

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

```cfg
set sd_phone_relay_url "wss://YOUR_RELAY_HOST/PATH"
set sd_phone_relay_key "YOUR_64_CHARACTER_HEX_KEY"
```

{% endcode %}

</details>

<details>

<summary>The screen view does not open for a player others are already watching</summary>

**Cause.** `screen.maxWatchers` staff members are already watching that player from inside the game.

**Fix.** Wait for one to stop, or raise `screen.maxWatchers`. Each viewer adds upload load.

</details>

<details>

<summary>The microphone button does nothing during the screen view</summary>

**Cause.** `screen.audio` is `false`.

**Fix.** Set `screen.audio = true` in `shared/config.lua`.

</details>

<details>

<summary>The console warns that the remote panel convars are missing</summary>

**Cause.** `remote.enabled` is `true` but `cuxial_admin_remote_url` or `cuxial_admin_remote_secret` is not set. The remote panel stays off; the in-game panel is not affected.

**Fix.** If you do not use the web panel, set `remote.enabled = false`. If you do, add both convars before the resource starts.

</details>

<details>

<summary>A staff member cannot enter the web panel</summary>

**Cause.** Their rank has remote access disabled, or they are not in the staff table. The console says which one. A rank given to a character only works from outside after that character has joined the server once with Discord linked.

**Fix.** Enable remote access on the rank from the panel, or have the staff member join once with that character.

</details>

<details>

<summary>A rank given to a Discord role is not applied</summary>

**Cause.** Role ranks need the external web panel service, which reports who holds each role.

**Fix.** Connect the web panel service, or give the rank by Discord account or by character.

</details>

<details>

<summary>I cannot grant, edit or delete a rank</summary>

**Cause.** One of these:

* The rank has a permission you do not hold yourself.
* The person already holds a rank with permissions you do not hold.
* You are trying to remove your own rank.
* You are deleting a rank that someone still has.

**Fix.** Ask someone with a higher rank, or remove the rank from its members before deleting it.

</details>

<details>

<summary>I edited the ranks in data/permissions.lua and nothing changed</summary>

**Cause.** `seed` is only used the first time the resource starts, when the ranks table is empty.

**Fix.** Edit ranks from the panel.

</details>

<details>

<summary>Where do I ban a player?</summary>

**Cause.** The panel issues warnings and kicks. Bans belong to txAdmin.

**Fix.** Ban from txAdmin. The ban is then listed in the sanctions history.

</details>

<details>

<summary>Taking keys says the key system is not running</summary>

**Cause.** `cuxial_garages` is not started.

**Fix.** Start `cuxial_garages`. Without it, vehicles spawned from the panel still appear, but without keys.

</details>

<details>

<summary>The appearance editor does not open</summary>

**Cause.** `cuxial_appearance` is not started.

**Fix.** Start `cuxial_appearance`.

</details>

<details>

<summary>Community service actions fail</summary>

**Cause.** `cuxial_cmservices` is not started.

**Fix.** Start `cuxial_cmservices`.

</details>

<details>

<summary>There is no zone selector for the weather</summary>

**Cause.** Weather by zones only exists with `av_weather`. With `prim_climatime`, or with no weather resource, the weather is the same for the whole map.

**Fix.** Use `av_weather` to set the weather by zones.

</details>

<details>

<summary>A report disappeared</summary>

**Cause.** Open reports live in memory. A report is discarded when its player disconnects, returns to character selection, or when the resource restarts. Only closed reports are stored.

**Fix.** Close a report to keep its transcript. Transcripts are deleted after `reportRetentionDays`.

</details>

<details>

<summary>A player cannot send more messages in their report</summary>

**Cause.** They reached `limits.messagesPerReport`, or they are writing faster than `limits.messageCooldown`.

**Fix.** Reply to or close the report. Raise the limit in `shared/config.lua` if it is too low for your server.

</details>

<details>

<summary>Names above players do not show at long distance</summary>

**Cause.** Players beyond the network radius are not loaded on the staff member's client.

**Fix.** Raise `nameplates.cullingRadius` and `nameplates.range`. A larger radius uses more bandwidth for that staff member while names are on.

</details>

<details>

<summary>Giving cash adds nothing to the framework balance</summary>

**Cause.** `cash` is listed in `moneyItems`, so it is given as an inventory item.

**Fix.** Remove `cash` from `moneyItems` to give it as a balance, or make sure the item exists in your inventory.

</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/core/cuxial-admin/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.