> 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/leisure/cuxial-pvp/troubleshooting.md).

# Troubleshooting

Common Cuxial PvP problems, with their cause and fix.

The most frequent problems after installing Cuxial PvP, 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 script. Cuxial PvP needs OneSync, `ox_lib` and `cuxial_bridge`.

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

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

```cfg
ensure ox_lib
ensure cuxial_bridge
ensure CuxiaPvP
```

{% endcode %}

</details>

<details>

<summary>The export fails with "No such export"</summary>

**Cause.** The folder was renamed. The exports are called through the resource name.

**Fix.** Keep the folder as `CuxiaPvP`, or use your new folder name in every call: `exports.<folder>:toggleUI(true)`.

</details>

<details>

<summary>No key opens the menu</summary>

**Cause.** The menu key has no default binding, so it does not collide with other resources.

**Fix.** Use `/Cuxiall`, bind "Open CuxiaPvP" in the FiveM key settings, or open the menu from your own resource with `exports.CuxiaPvP:toggleUI(true)`.

</details>

<details>

<summary>The command runs but no menu appears</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 package you downloaded, making sure `web/build` is uploaded in full, then restart the resource.

</details>

<details>

<summary>Players start a duel with no weapon</summary>

**Cause.** The weapon chosen does not exist on your server. The weapons in `data/weapons.lua` are examples and include add-on weapons.

**Fix.** Leave in `data/weapons.lua` only weapons your server has, and add their pictures to `web/build/weapons`. Do the same with `ladder` and `finisher` in `data/gungame.lua`.

</details>

<details>

<summary>Players fall through the map when a duel starts</summary>

**Cause.** The map uses coordinates of an arena that is not on your server. The maps in `data/maps.lua` are examples.

**Fix.** Replace the spawn points of each map with coordinates of your own arenas, or remove the maps you do not have.

</details>

<details>

<summary>Players stay dead between rounds or after the match</summary>

**Cause.** The events in `revive.events` do not belong to your ambulance script, or `revive.enabled` is `false`.

**Fix.** Put the client revive event of your ambulance script in `revive.events` and set `revive.enabled = true`. See [Configuration](/scripts/leisure/cuxial-pvp/configuration.md).

</details>

<details>

<summary>The time of day does not change, or stays frozen after the match</summary>

**Cause.** `weatherSystem` does not match the time script you run.

**Fix.** Set `weatherSystem = 'av'` for `av_weather` or `'cd'` for `cd_easytime` in `data/config.lua`.

</details>

<details>

<summary>"No zones configured for this game mode" when creating a Gun Game</summary>

**Cause.** `data/gungame_zones.lua` has no zones.

**Fix.** Draw one in game with `/pvpzone gungame <name>`. See [Commands & permissions](/scripts/leisure/cuxial-pvp/commands.md#zone-tool).

</details>

<details>

<summary>"Could not save the zone"</summary>

**Cause.** The player does not have the ACE permission, or the zone has fewer than three corners.

**Fix.** Grant the permission and draw the zone again:

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

```cfg
add_ace group.admin cuxialpvp.zones allow
```

{% endcode %}

</details>

<details>

<summary>"cuxial_bridge or its zone tool is missing"</summary>

**Cause.** The installed `cuxial_bridge` is older than the one delivered with the script.

**Fix.** Update `cuxial_bridge` to the version included in your download and restart the server.

</details>

<details>

<summary>A map, weapon or zone shows no picture</summary>

**Cause.** The picture is missing or its name does not match the `value` of the entry.

**Fix.** Name the file exactly like the `value`, upper and lower case included:

| Entry         | Picture                         |
| ------------- | ------------------------------- |
| Map           | `web/build/maps/<value>.png`    |
| Duel weapon   | `web/build/weapons/<value>.png` |
| Gun Game zone | `web/build/zones/<value>.webp`  |

Ladder weapons of Gun Game take their icon from `ox_inventory`.

</details>

<details>

<summary>Everyone shows the default Discord avatar</summary>

**Cause.** `discord.botToken` is empty or not valid. Players without a linked Discord account always show the default avatar.

**Fix.** Create a bot in the Discord developer portal and paste its token in `discord.botToken` of `data/config.lua`. The bot needs no permissions.

</details>

<details>

<summary>A player cannot place a bet</summary>

**Cause.** Bets are paid in cash, and each player can bet once per match.

**Fix.** The player needs the amount in cash, not in the bank.

</details>

<details>

<summary>"You already have a lobby open" or "No room for more lobbies right now"</summary>

**Cause.** The limits of `data/config.lua` were reached.

**Fix.** Raise `limits.maxLobbiesPerHost` or `limits.maxLobbies`. See [Configuration](/scripts/leisure/cuxial-pvp/configuration.md).

</details>

<details>

<summary>The leaderboard is empty after every restart</summary>

**Cause.** `leaderboard.clearOnRestart` is `true`.

**Fix.** Set it to `false` in `data/config.lua`.

</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/leisure/cuxial-pvp/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.