Troubleshooting

Audio Issues

No Sound at All

Symptoms: CarPlay UI opens and shows track info, but no audio plays. No music audible from any vehicle.

Solutions:

1. Verify xsound is running

   ensure xsound

2. Check xsound version — Ensure you have the latest version of xsound installed. Older versions may not support all 3D audio features
3. Check ensure order — xsound must start before oxide-carplay

   ensure ox_lib
   ensure community_bridge
   ensure xsound
   ensure oxide-carplay

4. Check client console — Press F8 and look for xsound-related errors. Verify the YouTube URL is valid and accessible

Music Too Quiet / Too Loud

Symptoms: Volume doesn't match expectations. Other players can't hear music from your vehicle.

Solutions:

1. Check in-game volume — The CarPlay volume slider (0-100) controls the base volume. Default is 50 (Config.CarPlay.DefaultVolume)
2. Check vehicle state — Closed windows/doors reduce volume by VolumeMultClosed (default 0.15x). Open a window or door for louder external audio
3. Adjust audio range

   Config.CarPlay.AudioRange = 15.0        -- Increase for louder outdoor range
   Config.CarPlay.AudioRangeClosed = 4.0   -- Increase for louder muffled range
   Config.CarPlay.VolumeMultClosed = 0.25  -- Increase muffled volume (0.0-1.0)

Playback Issues

YouTube URL Not Working

Symptoms: Pasting a URL does nothing. "No track selected" persists after pressing Play.

Solutions:

1. Check URL format
   • Supported: https://www.youtube.com/watch?v=VIDEO_ID
   • Supported: https://youtu.be/VIDEO_ID
   • Not supported: YouTube Shorts, YouTube Music, private/age-restricted videos
2. Check server console — Enable debug mode and look for metadata fetch errors. The server contacts noembed.com to fetch video info — ensure outbound HTTP is not blocked
3. Check for rate limiting — noembed.com may rate-limit requests if many players are using CarPlay simultaneously. The system will retry automatically

Songs Not Auto-Advancing

Symptoms: Current track ends but the next queued track doesn't play. Queue shows tracks but playback stops.

Solutions:

1. Check queue contents — The queue must have at least one track for auto-advance. Verify tracks are visible in the Queue tab
2. Check xsound callbacks — Song end detection relies on xsound's onPlayEnd callback. Restart the resource if detection appears stuck:

   restart oxide-carplay

3. Enable debug mode — Look for "song ended" or "playing next" messages in the console

Queue Full

Symptoms: Cannot add more tracks to the queue.

Solutions:

1. Check queue limit — Default maximum is 20 tracks (Config.CarPlay.MaxQueueSize). Remove tracks or save the queue as a playlist, then clear it

UI Issues

CarPlay Not Opening

Symptoms: Pressing M does nothing. No UI appears.

Solutions:

1. Check you are in a vehicle — CarPlay only opens when seated in a vehicle
2. Check keybind — Default key is M (Config.CarPlay.Keybind). Check FiveM key settings for conflicts with other resources
3. Check CarPlay is enabled

   Config.CarPlay.Enabled = true

4. Check resource is running — Verify oxide-carplay is started in the server console

Map Not Loading

Symptoms: Map tab shows a blank area. No tiles visible.

Solutions:

1. Check NUI — Press F8 and look for JavaScript errors. Verify fxmanifest.lua includes ui_page 'web/dist/index.html'
2. Check map tiles — Verify web/dist/map-tiles/ contains 20 JPG tile images. Missing tiles result in blank areas on the map
3. Verify resource integrity — Re-download the resource if files appear missing or corrupted

Sync Issues

Passengers Not Hearing Music

Symptoms: Driver hears music but passengers do not. Passengers see the UI but hear nothing.

Solutions:

1. Check xsound on passenger client — The passenger's client must also have xsound functioning. Press F8 on the passenger's client for errors
2. Check statebag sync — Music state is synced via the oxide:carplay vehicle statebag. Enable debug mode and check both driver and passenger consoles
3. Check proximity scan — The passenger's proximity scan should detect the vehicle's music. Default scan interval: Config.CarPlay.ProximityScanInterval = 2000 (2 seconds). Wait a few seconds after entering the vehicle

Music Persists After Leaving Vehicle

Symptoms: Audio continues playing after exiting the vehicle. Sound doesn't fade out.

Solutions:

1. Walk further away — Sound cleanup triggers at 50m+ distance from the vehicle. The proximity scan will clean up desynced sounds
2. Restart the resource

   restart oxide-carplay

Jailbreak Issues

Item Not Working

Symptoms: Using the USB item does nothing. No progress bar or animation.

Solutions:

1. Check item is registered — The carplayjb_usb item must be registered in your inventory resource. See the Installation Guide for setup instructions
2. Check you are in a vehicle — Jailbreak requires the player to be seated in a vehicle
3. Check vehicle is not already jailbroken — Each vehicle can only be jailbroken once. The console shows "Already jailbroken" if attempted again
4. Check item name matches config — Config.Jailbreak.RequiredItem must match the item name in your inventory resource. Default: 'carplayjb_usb'

Minigame Not Appearing

Symptoms: Progress bar completes but no circuit trace minigame shows. Screen goes blank after progress bar.

Solutions:

1. Check NUI errors — Press F8 and look for JavaScript errors related to circuitTrace
2. Check NUI focus — The minigame requires NUI focus to receive input. Other resources stealing NUI focus may interfere

Performance

Tuning Intervals

If you experience performance issues, adjust these intervals:

Setting	Default	Reduce CPU	Description
PositionUpdateInterval	150	Increase to 300	3D audio position tracking
ProximityScanInterval	2000	Increase to 5000	Nearby vehicle discovery
MapUpdateInterval	500	Increase to 1000	NUI map position refresh

-- Performance-friendly settings
Config.CarPlay.PositionUpdateInterval = 300
Config.CarPlay.ProximityScanInterval = 5000
Config.CarPlay.MapUpdateInterval = 1000

Higher intervals mean less frequent updates (slightly less smooth) but lower CPU usage.

Many Vehicles Playing Music

If many vehicles play music simultaneously in a small area:

1. Reduce audio range to limit xsound instances per client

   Config.CarPlay.AudioRange = 8.0

2. Increase proximity scan interval to reduce scan overhead

   Config.CarPlay.ProximityScanInterval = 5000

Debug Mode

Enable comprehensive logging:

-- shared/config.lua
Config.Debug = true

Console output includes:

• Resource initialization
• YouTube metadata fetch results
• Playlist save/load operations
• Jailbreak attempts and results
• Statebag state changes
• Proximity scan activity
• Audio playback start/stop events

Log prefix: [oxide-carplay]

Disable in production to reduce console spam.

Getting Help

If issues persist:

1. Enable debug mode and collect console output
2. Check server console for errors during the issue
3. Check client console (F8) for JavaScript or NUI errors
4. Verify xsound is running and up to date
5. Verify community_bridge is running and up to date
6. Test with minimal resources to isolate conflicts