# troubleshooting

<details>

<summary>No sound plays at all</summary>

**Check xsound start order.**\
`xsound` must be started before `moh_carplay` in `server.cfg`:

```cfg
ensure xsound        # ← must come first
ensure moh_carplay
```

**Check the URL format.**\
The URL must be a direct link to an audio file, not a webpage:

```
✅  https://example.com/song.mp3
❌  https://soundcloud.com/artist/track
❌  https://open.spotify.com/track/...
```

**Check your server console.**\
xsound errors appear there when a URL fails to load. An HTTP 403 or 404 means the file is not accessible from the server.

</details>

<details>

<summary>Music stops when I leave the vehicle</summary>

This is **intended behaviour**. When you exit a vehicle, playback pauses and the timestamp is saved to the statebag. When you re-enter, it resumes from where it left off.

If you want music to continue playing while outside the vehicle, this feature would need a code change.

</details>

<details>

<summary>Other passengers cannot hear the music</summary>

**OneSync is not enabled.**\
Statebags and entity replication require OneSync. Add this to `server.cfg`:

```cfg
set onesync on
```

**xsound audible range.**\
xsound has a maximum 3D audio range. If a passenger is too far from the vehicle entity, the volume may be zero. Check xsound's documentation for range configuration.

**Player joined after the song ended.**\
If the song finished before the player entered, `currentSong` is already `nil` on the statebag and there is nothing to resume. They will hear the next song that is played.

</details>

<details>

<summary>Command not found</summary>

Confirm `Config.Command` is set and the resource restarted after the change:

```lua
Config.Command = "music"  -- players type /music
```

Run `restart moh_carplay` in the server console after any config change.

</details>

<details>

<summary>Error: attempt to index a nil value (Framework)</summary>

The framework object failed to load. Make sure:

* `Config.Framework` matches the exact resource name on your server.
* The framework resource is started before `moh_carplay`.
* For QBCore: the export is `qb-core`, not `QBCore`.
* For ESX: the export is `es_extended`.

</details>

<details>

<summary>Song timestamp desyncs after rejoining</summary>

This can happen if the update loop interval is too high or if xsound takes time to seek after a reload. Try lowering `Config.SeekWait` slightly:

```lua
Config.SeekWait = 100  -- increase if seeking feels unreliable
```

</details>

<details>

<summary>Console warning: "Player X sent syncmusic but is not in vehicle"</summary>

This is the server-side ownership check working correctly. It means a client sent the sync event while not inside the target vehicle, and the request was safely dropped. If you see this for legitimate players, check whether `GetVehiclePedIsIn` is returning the correct vehicle on the client side.

</details>

<details>

<summary>Ghost sounds after `restart moh_carplay`</summary>

The resource stop handler should clean up all sounds automatically. If ghost sounds persist:

1. Make sure `onResourceStop` is not being blocked by another script.
2. Run `restart xsound` to force-clear all active sounds.
3. Check whether `spawnedSounds` is being populated correctly (requires a code inspection).

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://mohssins.gitbook.io/mohscriptsdocs/moh-carplay/troubleshooting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.