Troubleshooting

Shift Issues

Can't Clock In

Symptoms: Player interacts with the dispatcher but cannot clock in. Error notification appears.

Solutions:

1. No slots available — Check if the location has reached Config.MaxSlotsPerLocation (default: 3). Wait for another player to clock out, or increase the limit in shared/config.lua
2. Already clocked in — The player already has an active shift. Clock out first before clocking in again
3. Suspended — The player has accumulated too many complaints and is temporarily banned. Check the suspension timer in the dispatcher menu. The timeout duration is configured via Config.Complaints.timeoutMinutes (default: 30 minutes)
4. Spawn area occupied — Another player or vehicle is blocking the tow truck spawn point. Wait for the area to clear
5. Rate limited — The clock-in action has a 2-second cooldown. Wait and try again

Dispatcher Menu Not Appearing

Symptoms: Third-eye target doesn't show on the dispatcher NPC, or the menu doesn't open.

Solutions:

1. Verify your targeting resource is working (ox_target, qb-target, etc.) and is supported by community_bridge
2. Check that the NPC spawned correctly — look for the auto shop worker model at the tow yard coordinates
3. Ensure the player's character is loaded (community_bridge OnPlayerLoaded event must have fired)
4. Check the server console for resource start errors

NPC Not Spawning

Symptoms: No dispatcher NPC visible at the tow yard.

Solutions:

1. Verify the NPC model s_m_m_autoshop_01 is valid and not blocked by your server
2. Check that Config.Locations has valid coordinates
3. Look for errors in the client console related to model loading
4. Ensure the resource started without errors

---

Call Dispatch Issues

No Calls Being Dispatched

Symptoms: Player clocks in but never receives a service call.

Solutions:

1. Ensure the player is in WAITING state (not already on a call or working)
2. Calls are dispatched at random intervals between 15–45 seconds. Wait for at least 1 minute
3. Check debug mode output for dispatch timer messages
4. Verify Config.Calls settings are reasonable (not set to extremely long intervals)
5. If in a crew, only the leader receives and accepts calls

Call Notification Not Appearing

Symptoms: Server logs show a call was dispatched but no notification appears on screen.

Solutions:

1. Ensure the NUI frontend is loaded (check web/dist/index.html exists)
2. Check the F8 console for JavaScript errors
3. The incoming call uses keyboard input (E to accept, Backspace to decline) — not mouse focus

Auto Clock-Out After Missed Calls

Symptoms: Player is automatically clocked out unexpectedly.

This is intended behavior. After 3 missed or declined calls (configurable via Config.Calls.maxMissedCalls), the player is automatically clocked out. To adjust:

• Increase Config.Calls.maxMissedCalls in shared/config/job.lua
• Increase Config.Calls.responseTimeSeconds to give more time to respond

---

Vehicle Issues

Tow Truck Not Spawning

Symptoms: Player clocks in but no tow truck appears at the tow yard.

Solutions:

1. Check that the vehicleSpawn coordinates in Config.Locations are valid and accessible
2. Verify the vehicle model towtruck (or your configured model) exists and isn't blocked
3. Check if another vehicle is blocking the spawn point — ensure the area around the vehicleSpawn coordinates is clear of persistent vehicles
4. Look for errors in the client console related to vehicle creation

No Vehicle Keys

Symptoms: Tow truck spawns but the player can't enter or drive it.

Solutions:

1. Verify your vehicle key system is configured in community_bridge
2. Check that Bridge.VehicleKey.GiveKeys is working with your key resource
3. The truck's plate is set to TOWSVC — ensure your key system can handle custom plates

Tow Truck Destroyed Mid-Shift

Symptoms: Current job cancelled, fine notification appears, dispatch stops.

This is intended behavior. When the truck's engine health drops below the destroyed threshold (default: 150):

• Current job is cancelled
• A complaint is added
• A $200 fine is deducted from cash
• Dispatch stops

To adjust sensitivity, modify Config.Vehicle.destroyedThreshold in shared/config/vehicles.lua.

---

Job Issues

Stranded Vehicle Not Spawning

Symptoms: Player accepts a call but no stranded vehicle appears at the event location.

Solutions:

1. Check that the event coordinates in Config.Events are valid road positions
2. Verify the vehicle model specified in the event exists
3. Check the client console for vehicle model loading errors
4. Ensure the location isn't underground or inside a building collision

NPC Driver Not Exiting Vehicle

Symptoms: The stranded NPC stays inside the vehicle and doesn't walk to the standing position.

Solutions:

1. The NPC exit sequence has an 8-second timeout — wait for it to complete
2. Check that the NPC model loaded correctly (from Config.DriverPeds)
3. If the vehicle is in a tight space, the NPC may not have room to exit

Tow Vehicle Detaching

Symptoms: The towed vehicle detaches from the tow truck mid-drive.

Solutions:

1. Drive carefully — sharp turns and high speeds can break the attachment
2. The tow distance warning system alerts you if you drive too far ahead
3. If the vehicle detaches, return to it to re-attach

Job Won't Complete

Symptoms: Player finishes the repair steps but the job doesn't register as complete.

Solutions:

1. For fuel help: ensure the refuelling animation played to completion
2. For wheel change: all three steps must complete (place jack, change wheel, remove jack)
3. For battery change: both remove and install steps must complete
4. For towing: must be at the delivery drop-off point within 20m
5. Check that props were returned to the truck where required
6. The complete action has a 5-second rate limit cooldown

---

Props Issues

Props Not Visible on Truck

Symptoms: Tow truck spawns but no props (jack, wheel, jerry can, battery) are visible on the bed.

Solutions:

1. Check that the prop models load correctly — verify models exist in your GTA installation
2. Look for client console errors related to CreateObject
3. Props attach to bone 3 (chassis) — verify the tow truck model has this bone

Can't Take Props from Truck

Symptoms: Third-eye targets for taking props don't appear on the tow truck.

Solutions:

1. Props are only available during WORKING state (must have an active job)
2. Check that the prop is in ON_TRUCK state (not already taken)
3. Verify target interactions are working with your targeting resource
4. Must be within 4m of the truck

Carry Animation Not Playing

Symptoms: Player takes a prop but no carry animation plays.

Solutions:

1. Check that animation dictionaries load correctly
2. Some server resources may interfere with ped animations — check for conflicts
3. The animation will clear automatically when returning the prop to the truck

---

Cone Issues

Cones Not on Truck

Symptoms: No cones visible on the tow truck bed.

Solutions:

1. Check that Config.Cones.enabled is true in shared/config/visuals.lua
2. Verify the cone model prop_roadcone01a loads correctly
3. Cones attach to Config.Cones.truckAttach positions on the truck

Ghost Preview Not Showing

Symptoms: Player takes a cone but no ghost placement preview appears.

Solutions:

1. The ghost preview uses camera raycasting — ensure the player is looking at a valid ground surface
2. Maximum placement range is 6m (configurable via Config.Cones.placementRange)
3. Check the F8 console for errors

Speed Zones Not Working

Symptoms: Cones are placed but traffic doesn't slow down.

Solutions:

1. Check that Config.SafetyZone.enabled is true
2. Speed zones are created per-cone, not globally — verify cones are actually placed
3. Speed zones affect NPC vehicles within the configured radii (15/30/50m)

---

Crew Issues

Can't Invite Partner

Symptoms: Invite fails or returns an error.

Solutions:

1. The leader must be clocked in and on an active shift
2. The leader must not already have a crew partner
3. Enter the target player's server ID (not character ID)
4. Both players must be within 15m of each other
5. The invite has a 5-second rate limit cooldown

Partner Not Receiving Invite

Symptoms: Leader sends invite but partner sees nothing.

Solutions:

1. The target player must not already be in a crew or on a shift
2. The target player must not have a pending invite from another player
3. If the partner is near the dispatcher NPC, the invite appears in their menu
4. Otherwise, a notification tells them to visit the dispatcher to accept
5. Invites expire after 60 seconds (configurable via Config.Crew.inviteTimeout)

Crew Sync Issues

Symptoms: Partner doesn't see the same job state or can't interact with the scene.

Solutions:

1. Job state is synchronized via server events — both players receive the same call data
2. The partner resolves the leader's vehicle via network ID — if the vehicle isn't loaded on the partner's client, there will be a delay
3. If sync issues persist, the leader can clock out and back in

Vehicle Transfer Problems

Symptoms: When the leader clocks out, the partner can't use the vehicle.

Solutions:

1. Vehicle ownership transfers automatically via RoadsideVehicle.TakeOwnership()
2. If the vehicle entity doesn't resolve on the partner's client, wait for network sync
3. The partner's health monitor restarts after transfer

---

Payment Issues

Not Receiving Payment

Symptoms: Player completes jobs but doesn't get paid.

Solutions:

1. Payment is issued as a lump sum to the bank account when clocking out, not per job
2. Check the shift summary (NUI screen or email) for the payment breakdown
3. Verify community_bridge framework payment functions are working
4. Check the server console for errors related to Bridge.Framework.AddAccountBalance

Incorrect Amounts

Symptoms: Payment seems too low or too high.

Solutions:

1. Review the payment breakdown in the shift summary
2. Check for late finish penalty (0.85x multiplier on late jobs)
3. Vehicle damage charges reduce the final payout
4. Gas fee (5%) and taxes (10%) are deducted from gross pay
5. Crew jobs include a 15% co-op bonus
6. Verify Config.Payment settings match expectations

Streak Not Counting

Symptoms: Daily streak doesn't increment.

Solutions:

1. Streaks are tracked by real-world calendar date
2. The streak only increments once per day (first job of the day)
3. Missing a day resets the streak to 1 (not 0)
4. Check the database last_job_date column for the character

---

Progression Issues

Level Not Updating

Symptoms: Player has enough jobs but hasn't leveled up.

Solutions:

1. Level-up is checked after each job — ensure the job completed successfully
2. Verify total_jobs in the database matches expectations
3. Check Config.Levels for the requiredJobs threshold
4. Level 5 is the maximum — no further progression

Complaints Not Resetting

Symptoms: Complaints stay at maximum even after jobs.

Solutions:

1. Each successful job reduces complaints by Config.Complaints.decayPerJob (default: 1)
2. If complaints reach maxComplaints (3), the player is suspended and complaints reset to 0
3. Check the database directly for the current complaint count

Timeout Not Expiring

Symptoms: Player is still suspended past the expected duration.

Solutions:

1. Check the timeout_until column in the database for the actual expiry time
2. Timeout is stored as a DATETIME and compared against os.time() on the server
3. Ensure the server's system clock is correct
4. Manually clear the timeout:

UPDATE roadsideassistancejob_progression SET timeout_until = NULL WHERE char_id = ?;

---

HUD and NUI Issues

Timer Not Showing

Symptoms: No timer display during active jobs.

Solutions:

1. Ensure the web UI was built: cd web && npm install && npm run build
2. Check that web/dist/index.html exists
3. Verify ui_page in fxmanifest.lua points to web/dist/index.html
4. Check the F8 console for NUI errors

NUI Stuck Open

Symptoms: Menu or summary screen won't close, cursor is stuck.

Solutions:

1. Try pressing Escape to close the menu
2. If the NUI focus is stuck, restart the resource
3. Check for JavaScript errors in the F8 console
4. As a last resort, reconnect to the server

Camera Issues in Menu

Symptoms: Menu camera doesn't appear or is positioned incorrectly.

Solutions:

1. The menu camera is configured per-location via menuCamera in Config.Locations
2. Camera uses a gentle sway animation for visual polish
3. If using bridge menu style (Config.menuStyle = 'menu'), no camera is used

Tutorial Tooltips Not Showing

Symptoms: No tutorial tooltips appear for new players.

Solutions:

1. Check that tutorials haven't been disabled: run /roadsidetutorials to re-enable
2. Run /roadsidetutorialreset to clear all seen state
3. Tutorials require Config.Tutorials to be defined in shared/config/tutorials.lua
4. Check the F8 console for NUI errors

---

Performance

Prop Cleanup

If props from a crashed resource remain in the world:

1. Restart the resource to trigger cleanup handlers
2. Vehicle, NPC, prop, and cone entities are cleaned up on shift end, character unload, and resource stop
3. Safety zones (speed zones and scenario blocks) are removed during cleanup

Thread Optimization

The resource uses several polling threads:

Thread	Sleep Interval	Active During
Vehicle health monitor	1000ms	Any shift state
NPC animation cycle	100–2000ms	Active job with NPC
Cone ghost preview	0ms	Placing a cone
Waypoint render	0ms (configurable)	Waypoint visible (H held)
Call input listener	0ms	Incoming call notification

Threads automatically stop when not needed and restart on demand.

---

Debug Mode

Enabling Debug Mode

Set Config.Debug = true in shared/config.lua and restart the resource. Debug messages are prefixed with [oxide-roadsideassistancejob] in both server and client consoles.

What Gets Logged

• Shift state transitions
• Clock in/out events with slot counts
• Dispatch timer starts and call dispatch events
• Call accept/reject/miss with missed call counts
• Job completion and payment calculations
• Crew formation, dissolution, and vehicle transfers
• Progression loading, saving, level-ups, and complaint changes
• Prop attachment and state changes
• Cone placement and speed zone creation
• Vehicle spawn, destruction, and health monitoring
• NPC spawn and cleanup
• Safety zone creation and removal

---

Getting Help

When reporting issues, include the following information:

• Server framework (ESX, QBCore, QBx, etc.)
• community_bridge version
• ox_lib version
• Error messages from the server console (F8 or terminal)
• Steps to reproduce the issue
• Whether the issue occurs solo or in a crew
• Current shift state when the issue occurred
• Debug mode output if available