Troubleshooting

Shift Issues

Can't Clock In

Symptoms: Player interacts with the supervisor 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 supervisor menu. The timeout duration is configured via Config.Complaints.timeoutMinutes (default: 30 minutes)
4. Rate limited - The clock-in action has a 2-second cooldown. Wait and try again

Supervisor Menu Not Appearing

Symptoms: Third-eye target doesn't show on the supervisor 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 postal worker model at the depot 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 supervisor NPC visible at depot locations.

Solutions:

1. Verify the NPC model s_m_m_postal_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

Vehicle Issues

Van Not Spawning

Symptoms: Player clocks in but no delivery van appears at the depot.

Solutions:

1. Check that the vehicleSpawn coordinates in Config.Locations are valid and accessible (not inside a building or underground)
2. Verify the vehicle model boxville2 (or your configured model) exists and isn't blocked
3. Check if another vehicle is blocking the spawn point - the resource clears a 25m area but persistent vehicles may remain
4. Look for errors in the client console related to Bridge.Utility.CreateVehicle

No Vehicle Keys

Symptoms: Van 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 van's plate is set to GOPOST - ensure your key system can handle custom plates

Van Destroyed Mid-Shift

Symptoms: Deliveries cancelled, complaint notification appears.

Solutions:

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

• Current deliveries are cancelled
• A complaint is added
• A $150 fine is applied to the shift payout
• Player returns to CLOCKED_IN state and can request a new task

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

Boxes Not Appearing in Van

Symptoms: Player loads boxes but they don't appear visually inside the van.

Solutions:

1. Check that the box model prop_cs_cardbox_01 loads correctly
2. Verify Config.VanBoxOffsets has enough entries for your batch size
3. In crew mode, only the player who loaded the box sees the prop locally - the partner sees a synced count

Loading Issues

Pallet Not Spawning

Symptoms: Player clocks in but no pallet appears at the pickup point.

Solutions:

1. Check that pickupPoints in the location config has valid vector4 coordinates
2. Verify the pallet model bkr_prop_coke_pallet_01a loads correctly
3. Ensure the pickup point isn't underground or inside a collision

Can't Pick Up Box

Symptoms: Third-eye target on boxes doesn't appear or doesn't work.

Solutions:

1. Ensure the player is not already carrying a box (isCarrying must be false)
2. Verify the player is in LOADING shift state
3. Check that the player is not in a vehicle
4. Ensure the box entity still exists (wasn't already picked up)

Box Won't Load Into Van

Symptoms: Player carrying a box but can't interact with the van to load it.

Solutions:

1. Rear doors must be open - The van's rear doors (indices 2, 3) must be physically open
2. Must be near the rear - Player must be within 3.5m of the van's rear (offset -4.0 on Y axis)
3. Must be carrying - Player must have an active carry prop
4. Must be in LOADING state - Check the current shift state

Post Box Not Appearing (Letters)

Symptoms: GPS blip appears for post box but no interaction target.

Solutions:

1. The post box uses a sphere zone target at the coordinates - no physical prop is spawned. Walk to the blip location and check for the third-eye prompt
2. Verify postBoxes in the location config has valid vector4 entries
3. Ensure the player is not already carrying a mail bag

Delivery Issues

Blip Not Appearing

Symptoms: No delivery destination blip on the map after loading is complete.

Solutions:

1. Ensure the shift transitioned to DELIVERING state
2. Check that delivery orders were generated successfully (debug log shows order count)
3. Verify deliveryZones in the location config has entries matching the player's level

Customer Not Spawning

Symptoms: Player delivers a package but no customer NPC appears.

Solutions:

1. Check that Config.CustomerPeds models are valid
2. The system tries all models in random order - if all fail to load, a fallback notification appears
3. Customer NPCs are only spawned for package deliveries, not letters

Can't Deliver Package

Symptoms: Player is at the delivery marker with a package but can't deliver.

Solutions:

1. Player must be carrying a package (grabbed from van)
2. Player must be within 3m of the delivery zone coordinates
3. Player must not be in a vehicle
4. Player must not be downed or dead
5. Press E to deliver (the prompt appears via NUI hint text)

Timer Issues

Symptoms: Timer seems inaccurate or doesn't match expected duration.

Solutions:

1. The timer is server-authoritative. The client timer is a visual backup
2. Timer formula: baseTime (60s) + distance * timePerDistanceUnit (0.25s/unit)
3. If the timer expires, the delivery still works but earns a 15% penalty
4. Check Config.Timer settings in shared/config/job.lua

Letterbox Not Targetable

Symptoms: Player is near a letterbox delivery point but can't interact.

Solutions:

1. Letterbox delivery uses a sphere zone target at the zone coordinates, not the physical prop
2. The player must not be in a vehicle
3. The shift must be in DELIVERING state
4. Only one letterbox target is active at a time (the current delivery)

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. 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 supervisor NPC, the invite appears in the menu
4. Otherwise, a notification tells them to visit the supervisor to accept
5. Invites expire after 60 seconds (configurable via Config.Crew.inviteTimeout)

Crew Sync Issues

Symptoms: Partner doesn't see boxes, or delivery states are out of sync.

Solutions:

1. Box counts are server-authoritative and synced via events
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. Both crew members receive the same delivery orders from the server
4. 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 PostalVehicle.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 deliveries but doesn't get paid.

Solutions:

1. Payment is issued as a lump sum when clocking out, not per delivery
2. Check the shift summary screen 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 early finish penalty (clocking out with undelivered packages)
3. Vehicle damage charges reduce the final payout
4. Crew deliveries include a 15% co-op bonus
5. 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 delivery of the day)
3. Missing a day resets the streak to 1 (not 0)
4. Check the database last_delivery_date column for the character

Progression Issues

Level Not Updating

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

Solutions:

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

Complaints Not Resetting

Symptoms: Complaints stay at maximum even after deliveries.

Solutions:

1. Each successful delivery reduces complaints by Config.Complaints.decayPerDelivery (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 postaljob_progression SET timeout_until = NULL WHERE char_id = ?

HUD & NUI Issues

Delivery Panel Not Showing

Symptoms: No timer or progress display during deliveries.

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 the correct path
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 positioned at vector3(157.78, 82.48, 104.90) looking at the GoPostal building
2. If your depot is in a different location, the camera still shows the default GoPostal building (cosmetic only)
3. Camera uses a gentle sway animation for visual polish

Performance

High Entity Count

Symptoms: FPS drops near depot areas.

Solutions:

1. Reduce Config.Pallet.maxVisibleBoxes (default: 12) if many players are loading simultaneously
2. Bystander pallets use non-networked entities with disabled collision for minimal impact
3. Bystander entities auto-despawn when players move out of range (broadcastRange + 50m)

Prop Cleanup

If props from a crashed resource remain in the world:

1. Restart the resource to trigger cleanup handlers
2. Bystander entities are cleaned up automatically on resource stop
3. Vehicle and pallet entities are cleaned up on shift end and character unload

Thread Optimization

The resource uses several polling threads:

Thread	Sleep Interval	Active During
Delivery proximity	0ms (near marker) / 500ms (far)	DELIVERING state
Vehicle health monitor	1000ms	Any shift state
Bystander proximity	5000ms	IDLE state with nearby pallets
Waypoint render	0ms (configurable)	Waypoint visible

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-postaljob] in both server and client consoles.

What Gets Logged

• Shift state transitions
• Clock in/out events with slot counts
• Delivery order generation
• Box pickup and loading events
• Payment calculations
• Crew formation and dissolution
• Pallet spawn and cleanup
• Vehicle spawn and destruction
• Progression level-ups and complaint changes
• Bystander sync events

Console Prefix

All debug messages use the format:

[oxide-postaljob] <message>

Getting Help

When reporting issues, include the following information:

• Server framework (ESX, QBCore, Oxide, 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