Troubleshooting

Solutions for common issues with oxide-carplay.

Startup and Dependency Issues

Resource fails to start

Check startup order:

ensure ox_lib
ensure o-link
ensure xsound
ensure oxide-carplay

Confirm the manifest dependencies exist and are started before oxide-carplay.

o-link features are missing

This resource expects working o-link modules for:

• character lookup
• usable items
• inventory
• progress bar
• notifications
• weather/time

If CarPlay starts but item use, notifications, or map weather/time are missing, verify your o-link integration first.

Audio Issues

No sound at all

Checks:

1. Verify xsound is started.
2. Confirm the pasted URL is a standard YouTube video URL.
3. Check client F8 for xsound or NUI errors.
4. Confirm the resource started after xsound.

Audio is too quiet outside the car

Review:

Config.CarPlay.AudioRange = 12.0
Config.CarPlay.AudioRangeClosed = 2.0
Config.CarPlay.VolumeMultClosed = 0.15

Remember:

• closed vehicles intentionally sound muffled
• sound becomes louder and carries further when doors or windows are open
• speed also increases effective range

Music keeps playing after leaving a vehicle

Current behavior:

• local state is cleared when you switch vehicles
• on foot, playback remains until you move far enough away or the vehicle playback state ends

If cleanup seems stuck:

1. Walk farther from the vehicle.
2. Wait for the proximity scan to reconcile state.
3. Restart oxide-carplay if the state is clearly desynced.

Playback and URL Issues

YouTube URL does not play

Checks:

1. Use a standard youtube.com/watch or youtu.be URL.
2. Enable Config.Debug = true and watch server output.
3. Confirm outbound HTTP requests are allowed from the server.

External lookups used by the resource:

• noembed.com
• pipedapi.kavin.rocks
• inv.nadeko.net

Playlist import fails

Checks:

1. Confirm the URL includes a list= parameter.
2. Verify the external playlist providers are reachable.
3. Confirm the queue is not already full.

Queue stops advancing

Auto-advance depends on xsound end callbacks.

Checks:

1. Make sure the queue still contains tracks.
2. Check F8 for playback errors.
3. Restart the resource if a specific playback instance is stuck.

UI and Map Issues

CarPlay does not open

Checks:

1. Confirm you are inside a vehicle.
2. Confirm Config.CarPlay.Enabled = true.
3. Check for keybind conflicts in FiveM settings.
4. Verify the resource is actually running.

Mini-player does not appear

Checks:

1. Make sure music is still playing when the main UI closes.
2. Confirm Config.CarPlay.MiniPlayer.Enabled = true.
3. Confirm the player's saved miniPlayerEnabled setting was not turned off in the Settings screen.

Settings are not persisting

Checks:

1. Confirm o-link.character.GetIdentifier is returning a character ID on your server.
2. Check server console for callback or KVP-related errors.
3. Verify the player is using a valid character session before testing saved settings or playlists.

Map loads blank or incomplete

Checks:

1. Confirm ui_page 'web/dist/index.html' is present in the manifest.
2. Confirm the packaged web/dist/map-tiles/ images exist.
3. Check F8 for NUI errors.
4. Verify o-link weather/time modules are working if labels are missing.

Sync Issues

Passengers do not hear the same track

Checks:

1. Verify xsound is working on all clients.
2. Confirm the vehicle has an oxide:carplay statebag while music is playing.
3. Wait for the proximity scan to resync nearby clients.
4. Check for client errors on both driver and passenger.

Repeat mode or queue state seems inconsistent

Repeat mode and queue are stored in the vehicle statebag. If clients disagree:

1. Have all occupants leave and re-enter the vehicle.
2. Restart playback from the controlling client.
3. Restart the resource if the statebag is clearly stuck.

Jailbreak Issues

USB item does nothing

Checks:

1. Confirm Config.Jailbreak.Enabled = true.
2. Confirm the item name matches Config.Jailbreak.RequiredItem.
3. Verify your o-link usable-item registration is working.
4. Confirm the player is seated in a vehicle.

Progress bar does not open

Checks:

1. Verify the o-link progress bar module is installed and working.
2. Check for client errors during item use.
3. Confirm the animation dictionary can load.

Item is not removed on success

Checks:

1. Confirm Config.Jailbreak.RemoveItem = true.
2. Verify the o-link inventory module supports HasItem and RemoveItem for your current setup.
3. Confirm the player still has the item at result time.

Success or failure notification does not show

Notifications are sent through olink.notify.Send.

If they are missing:

1. Verify the o-link notify module is configured.
2. Test another resource that uses the same notify path.

Weather/time or POIs are missing on the map after jailbreak

Checks:

1. Confirm the vehicle was actually marked jailbroken.
2. Confirm Config.Jailbreak.POIs contains valid coordinates.
3. Remember the default POIs in config are placeholders intended to be replaced.

Performance Tuning

If you need lower client overhead, review:

Config.CarPlay.PositionUpdateInterval = 150
Config.CarPlay.ProximityScanInterval = 2000
Config.CarPlay.MapUpdateInterval = 500

Higher intervals reduce update frequency and can lower CPU use at the cost of responsiveness.

You can also reduce:

Config.CarPlay.AudioRange = 12.0

Lower audio range means fewer nearby playback instances need to stay active.

Debug Mode

Enable debug output:

Config.Debug = true

Current debug prefix:

[oxide-carplay]

Use this when validating:

• startup flow
• metadata lookups
• playlist persistence
• playback sync
• jailbreak behavior

Getting Help

If issues persist:

1. Enable Config.Debug.
2. Collect server console output during the issue.
3. Check client F8 output for NUI or playback errors.
4. Verify xsound is working.
5. Verify the required o-link modules are functioning for your server.
6. Test with a reduced resource set to isolate conflicts.

Support

Need more help?

• Discord: https://discord.gg/dZ6q8FyGhm
• Website: https://www.oxidestudios.dev/
• o-link (required abstraction layer): https://github.com/WHEREISDAN/o-link