> 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/jobs/cuxial-diving/troubleshooting.md).

# Troubleshooting

Common Cuxial Diving problems, with their cause and fix.

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

<details>

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

**Cause.** A dependency is missing. Cuxial Diving needs OneSync, `ox_lib`, `oxmysql`, `cuxial_bridge`, `sleepless_interact`, `cuxial_jobs` and `cuxial_diving_assets`.

**Fix.** Check that the three folders of the package are in `resources` with their original names, enable OneSync and start the dependencies first:

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

```cfg
ensure ox_lib
ensure oxmysql
ensure ox_inventory
ensure sleepless_interact
ensure cuxial_bridge
ensure cuxial_jobs
ensure cuxial_diving_assets
ensure cuxial_diving
```

{% endcode %}

</details>

<details>

<summary>The console warns about items that do not exist in the inventory</summary>

**Cause.** On start the job checks every item it uses: tanks, mask, lift bag, loot and market. One or more are not defined in your inventory.

**Fix.** Add the entries of `install/items.lua` to your inventory. If you renamed any of them in your inventory, use the same names in `data/loot.lua` and `data/market.lua`.

</details>

<details>

<summary>The NPC is not there, or there is no option to talk to it</summary>

**Cause.** One of these:

* `npc.model` is not a valid ped model.
* `sleepless_interact` started after Cuxial Diving, so the interaction was registered on another target.
* You are farther than `npc.spawnDistance` or `npc.distance`.

**Fix.** Use a valid model, and start `sleepless_interact` before `cuxial_bridge` and `cuxial_diving`.

</details>

<details>

<summary>The panel does not open or stays empty</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>"Diving is still starting, try again in a few seconds"</summary>

**Cause.** The tables are not ready. Either the server has just started, or `oxmysql` could not create them.

**Fix.** Wait a few seconds. If the message stays, check the server console for `oxmysql` errors. The database user needs permission to create tables.

</details>

<details>

<summary>"You can't do this job"</summary>

**Cause.** `job` in `shared/config.lua` is a job name or a list, and the player's job is not in it. The check also applies to every crew member when the job starts.

**Fix.** Add the job to the list, or set `job = 'all'`.

</details>

<details>

<summary>A region cannot be picked</summary>

**Cause.** At least one member of the crew is below the `minLevel` of the region. The panel shows who.

**Fix.** Pick a lower region, or lower `minLevel` in `data/regions.lua`.

</details>

<details>

<summary>"There is a boat at the spawn point"</summary>

**Cause.** Every spawn point of the region has a vehicle within `run.spawnFreeRadius` metres. It can be the boat of another crew or any abandoned vehicle.

**Fix.** Clear the area, add more points to `spawns` in `data/regions.lua`, or lower `run.spawnFreeRadius`.

</details>

<details>

<summary>"The boat could not be spawned"</summary>

**Cause.** The server could not create the boat in time. OneSync is off, `boat.model` is not a valid boat, or the server is under load.

**Fix.** Enable OneSync, check `boat.model` and raise `boat.spawnTimeoutMs` if needed.

</details>

<details>

<summary>The crew cannot drive the boat</summary>

**Cause.** Your vehicle key system locks the boat. Cuxial Diving only hands out keys through `cuxial_garages`, and only with `boat.keys = true`.

**Fix.** Start `cuxial_garages` before `cuxial_diving`, or exempt the plates that start with the prefix of `boat.plate` in your own key system.

</details>

<details>

<summary>The tank or the mask does nothing when used</summary>

**Cause.** The script answers with the reason:

* "There is no job running": `gear.requireRun` is `true` and the player has no job in progress.
* "You can't do that in a vehicle": the gear cannot be put on while seated, including in the boat.
* "Put on a tank first": the mask needs a tank on.
* No message at all: the item name in your inventory is not the one written in `data/gear.lua`.

**Fix.** Stand up before using the gear, use the tank first, and keep the item names of `data/gear.lua`. Set `gear.requireRun = false` to allow the gear outside a job.

</details>

<details>

<summary>"The gear could not be equipped: refunded"</summary>

**Cause.** The player's game did not finish putting the gear on within `gear.confirmMs`, so the item was returned.

**Fix.** Try again. If it happens often, raise `gear.confirmMs`.

</details>

<details>

<summary>The pieces do not appear at the site</summary>

**Cause.** Pieces are placed when a crew member is within `site.spawnRadius` of the centre of a task, and they must end up underwater: below `site.surfaceZ` and no more than `site.maxDepthDelta` metres under the centre. A `center` on land, or far above the seabed, cannot be filled. The players see "The site could not be prepared, retrying".

**Fix.** Set `center` in `data/regions.lua` to a point on the seabed, with enough room around it for the `radius` and the `amount` of the task.

</details>

<details>

<summary>The suitcase cannot be opened</summary>

**Cause.** The player is not holding the weapon set in `suitcase.weapon`, a knife by default.

**Fix.** Hold the knife, sold at the job market, or set `suitcase.weapon = 'WEAPON_UNARMED'` to remove the requirement.

</details>

<details>

<summary>The rope cannot be thrown</summary>

**Cause.** One of these:

* The anchor is up. The script answers "Drop the anchor first".
* The box is still rising.
* The player is not seated in the boat or standing on its deck.
* The boat is farther than `tow.maxDistance` from the box.

**Fix.** Bring the boat close to the floating box, drop the anchor with <kbd>H</kbd> from a seat and throw the rope with <kbd>E</kbd>.

</details>

<details>

<summary>The lift bag shows a different prop</summary>

**Cause.** The model of `boxes.liftbagModel` is not available, so the script uses `boxes.liftbagFallback`. `cuxial_diving_assets` is incomplete or was not restarted after copying it.

**Fix.** Copy `cuxial_diving_assets` again from the package and restart the server.

</details>

<details>

<summary>The boat cannot be delivered</summary>

**Cause.** The required tasks are not finished, the boat is farther than `deliver.radius` from the drop-off point, or the player is not seated in the boat.

**Fix.** Finish the corals and the trash, sail to the drop-off blip and press <kbd>E</kbd> from a seat.

</details>

<details>

<summary>The market shows items without a picture or with their internal name</summary>

**Cause.** The pictures are read from the image folder of `ox_inventory`, and the names from the item definitions of your inventory.

**Fix.** Copy `install/images/*.webp` to `ox_inventory/web/images/` and make sure every item of `data/market.lua` exists in your inventory. Pictures must be `.webp` files named after the item.

</details>

<details>

<summary>Staff commands answer that the player has no permission</summary>

**Cause.** The player is not in the group set in `restricted`, `group.admin` by default.

**Fix.** Add the player to the group in `server.cfg`, or change `restricted` in the `commands` block.

</details>

<details>

<summary>/divingfast does nothing</summary>

**Cause.** Debug was off when the resource started, or the player has no job in progress.

**Fix.** Set `debug = true` or the convar `cuxial_diving_debug` to `1`, restart the resource and start a job.

</details>

<details>

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

**Cause.** The `keys` block only sets defaults. 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>Logs do not reach Discord</summary>

**Cause.** The webhook convar is empty, has a different name from `logs.convar`, or was set after the resource started.

**Fix.** Add the convar to `server.cfg` above the `ensure` line. It is read once, when the resource starts:

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

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

{% endcode %}

</details>

<details>

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

**Cause.** The job follows the `ox:locale` convar. Item names come from your inventory, not from the job.

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

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

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

{% endcode %}

</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/jobs/cuxial-diving/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.