> 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/vehicles/cuxial-chipeo/troubleshooting.md).

# Troubleshooting

Common Cuxial Chipeo problems, with their cause and fix.

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

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

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

```cfg
ensure oxmysql
ensure ox_lib
ensure cuxial_bridge
ensure cuxial_chipeo
```

{% endcode %}

</details>

<details>

<summary>Using an item does nothing</summary>

**Cause.** One of these:

* The item has no `client.export` line, or the export does not match `cuxial_chipeo.<item name>`.
* The item name in the inventory differs from the one in `shared/config.lua`.
* The resource folder was renamed, so the export points to a resource that does not exist.
* The server uses an inventory other than `ox_inventory`.

**Fix.** Copy the item definitions from [Installation](/scripts/vehicles/cuxial-chipeo/installation.md), keep the folder named `cuxial_chipeo` and restart the server.

</details>

<details>

<summary>"This vehicle can't hold a sound system"</summary>

**Cause.** The model is in `vehicles.blacklist`.

**Fix.** Remove the model from the list.

</details>

<details>

<summary>"Only the vehicle owner can do this"</summary>

**Cause.** When installing: `install.ownerOnly` is `true` and the player does not own the vehicle. When removing: `install.unmountOwnerOnly` is `true` and the player is neither the owner nor the one who installed it. A vehicle that is not in your framework's vehicle table has no owner.

**Fix.** Set the option to `false`, or have the owner do it. For equipment installed on a vehicle with no owner, only the installer can remove it while `unmountOwnerOnly` is `true`.

</details>

<details>

<summary>The radio does not open</summary>

**Cause.** The message tells which case it is:

* *No vehicle nearby*: you are on foot and no vehicle is within `remoteRange`.
* *This vehicle has no sound system*: the nearest vehicle has no equipment. On foot the command targets the nearest vehicle.
* *You can't control this radio*: you are outside and you are neither the owner nor the installer.

**Fix.** Get in the vehicle, or stand closer to it than to any other.

</details>

<details>

<summary>I changed keybind but the radio still opens with the old key</summary>

**Cause.** `keybind` 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>The link is rejected as invalid</summary>

**Cause.** Only direct links to an audio file are accepted. The link must start with `https://`, contain no spaces or quotes, be no longer than `library.maxUrlLength` and end in one of `library.allowedExtensions`. The address of a video or streaming page does not end in an audio extension.

**Fix.** Use a link that points to the file itself, such as one ending in `.mp3`. To accept other formats, add the extension to `library.allowedExtensions`.

</details>

<details>

<summary>The song plays but the head unit shows RAW and bass and equalizer do nothing</summary>

**Cause.** The site hosting the file does not allow other pages to process its audio (no CORS headers). The head unit then plays the file as it is: volume and distance work, but bass, punch, equalizer, the muffled cabin and 3D audio do not.

**Fix.** Host the file somewhere that sends CORS headers, or use another link.

</details>

<details>

<summary>The song is accepted but nothing sounds</summary>

**Cause.** The link has a valid form but the file cannot be loaded: it no longer exists, the host blocks outside access, or the format is not playable. The head unit shows a load error.

**Fix.** Open the link in a browser. If it does not play there on its own, it will not play in the game.

</details>

<details>

<summary>The equipment disappeared from a vehicle</summary>

**Cause.** The installation is saved by plate. If the plate changed, the vehicle counts as a different one.

**Fix.** Restore the plate, or install it again. From another resource you can move it with the `UninstallRadio` and `InstallRadio` exports. See [Exports & events](/scripts/vehicles/cuxial-chipeo/developers.md).

</details>

<details>

<summary>The music stops when the vehicle is stored or despawns</summary>

**Cause.** Playback belongs to the vehicle while it exists in the world. When the entity disappears, what was playing is discarded.

**Fix.** Press play again. The equipment, the inserted USB stick and its songs are kept.

</details>

<details>

<summary>The equipment fries too soon, or windows keep bursting</summary>

**Cause.** The `overheat` and `pressure` blocks are stricter than you want.

**Fix.** Raise `overheat.seconds` or `overheat.bassThreshold`, raise `pressure.seconds` or `pressure.volumeThreshold`, or set `enabled = false` in either block. See [Configuration](/scripts/vehicles/cuxial-chipeo/configuration.md).

</details>

<details>

<summary>/repairchipeo says "You are not a mechanic" or lists missing materials</summary>

**Cause.** The player's job is not in `mechanic.jobs`, or they lack some of the items of `mechanic.requirements`. The command does not check duty.

**Fix.** Add the job name with `= true` to `mechanic.jobs`, and make sure the material items exist in the inventory.

</details>

<details>

<summary>Using a speaker item does nothing, or the speaker cannot be used</summary>

**Cause.** One of these:

* The prop named in `items.medusas` does not exist on the server. The model fails to load and nothing is placed.
* No target is running. The speaker is placed but offers no options.
* No vehicle with equipment is within `medusa.pairRange`. The speaker is placed unpaired and the option to open the radio stays hidden until a car with equipment is close enough.
* The player already has `medusa.maxPerPlayer` speakers placed.

**Fix.** List only props your server streams, start a target supported by Cuxial Bridge, and place the speaker next to the car.

</details>

<details>

<summary>Staff cannot use /removeallchipeo or /removechipeo</summary>

**Cause.** The player does not have the framework permission named in `admin.permission`, `'admin'` by default.

**Fix.** Give that permission to your staff in your framework, or set `admin.permission` in `shared/config.lua` to the permission they already have, and restart the resource.

</details>

<details>

<summary>The head unit 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>Texts appear in the wrong language</summary>

**Cause.** The script 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>


---

# 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/vehicles/cuxial-chipeo/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.