Troubleshooting

Solutions for common issues with oxide-animalcontroljob, organized by problem domain.

---

Shift Issues

Can't Clock In

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
2. Already clocked in — Clock out first before clocking in again
3. Suspended — Player has accumulated too many complaints. Check the suspension timer (default: 30 minutes)
4. Spawn area occupied — Another vehicle is blocking the truck spawn point
5. Rate limited — The clock-in action has a 2-second cooldown

Dispatcher Menu Not Appearing

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 at the office 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

---

Call Dispatch Issues

No Calls Being Dispatched

1. Ensure the player is in WAITING state (not already on a call)
2. Calls are dispatched at random intervals between 15-45 seconds — wait at least 1 minute
3. Check debug mode output for dispatch timer messages
4. If in a crew, only the leader receives and accepts calls

Auto Clock-Out After Missed Calls

This is intended behavior. After 3 missed/declined calls, the player is automatically clocked out. Adjust Config.Calls.maxMissedCalls or Config.Calls.responseTimeSeconds as needed.

---

Vehicle Issues

Service Truck Not Spawning

1. Check that vehicleSpawn coordinates in Config.Locations are valid
2. Verify the vehicle model kennel (or your configured model) is installed and streamed correctly
3. Check if another vehicle is blocking the spawn point
4. Look for client console errors related to vehicle creation

No Vehicle Keys

1. Verify your vehicle key system is configured in community_bridge
2. Check that Bridge.VehicleKey.GiveKeys is working
3. The truck's plate is ACSVC — ensure your key system handles custom plates

---

Animal Issues

Animal Not Spawning

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

Animal Escaped

The animal moved beyond its escape radius from spawn. Increase the escape radius in shared/config/animals.lua or ensure event locations have enough open space.

Animal Killed

This happens when an animal takes lethal damage from any source. The dart gun is restricted to the active job animal, but other weapons or vehicle impacts can kill it.

Animal Woke Up

Sedation lasts 30 seconds. Players must load the animal before the timer expires, or tranquilize again. Increase Config.Tranquilizer.sedationDuration if needed.

---

Bait and Capture Issues

Can't Take Bait from Truck

1. Bait is only available during stray capture jobs (WORKING state with STRAY_CAPTURE)
2. Bait may already be placed — check if it's in the player's hand or on the ground
3. Verify target interactions work with your targeting resource

Animal Not Approaching Bait

1. Player must be 15m+ away from the bait before the animal approaches
2. There is a 5-second delay after the player leaves
3. If recently spooked, the animal takes 8 seconds to return
4. Check that the animal is in the ALIVE state

Can't Capture Animal

1. Must be within 2.5m capture range
2. The animal must be in a capturable state (near bait, not fleeing)
3. Check that the third-eye target is showing

---

Tranquilizer Issues

No Dart Gun After Clock-In

1. Verify weapon_g2 is registered in your inventory system
2. Check that Bridge.Inventory.AddItem is working
3. Look for server console errors related to dart weapon
4. If using a custom weapon, update Config.Tranquilizer.weaponHash

Darts Not Affecting Animal

1. Darts only affect the active job's animal while on shift
2. Check you are shooting the correct animal
3. If already sedated, darts have no additional effect
4. Verify the weapon hash matches config

Running Out of Darts

Each call provides 5 darts. Increase Config.Tranquilizer.ammoPerCall if needed. Some animals have higher health and require more hits.

---

Delivery Issues

Can't Load Animal into Truck

1. Truck must be within 3m of the animal
2. Animal must be SEDATED or CAPTURED (not ALIVE)
3. Verify the truck entity still exists

Can't Unload at Shelter

1. Must be within 5m of Config.ShelterDeliveryPoint
2. Animal must be in LOADED state
3. Verify delivery coordinates are correct

---

Crew Issues

Can't Invite Partner

1. Leader must be clocked in
2. Leader must not already have a partner
3. Enter the target player's server ID (not character ID)
4. 5-second rate limit cooldown

Partner Not Receiving Invite

1. Target must not already be in a crew or on a shift
2. If near the dispatcher NPC, invite appears in the menu
3. Otherwise, a notification directs them to the dispatcher
4. Invites expire after 60 seconds

---

Payment Issues

Not Receiving Payment

1. Payment is issued as a lump sum on clock-out, not per job
2. Check the shift summary for the breakdown
3. Verify community_bridge framework payment functions are working

Incorrect Amounts

1. Review the payment breakdown in shift summary
2. Check for late finish penalty (0.85x)
3. Vehicle damage charges reduce the final payout
4. Gas fee (5%) and taxes (10%) are deducted

---

Progression Issues

Level Not Updating

1. Level-up is checked after each successful job
2. Verify total_jobs in the database
3. Check Config.Levels for requiredJobs thresholds
4. Level 5 is the maximum

Timeout Not Expiring

1. Check timeout_until column in the database
2. Ensure the server's system clock is correct
3. Manually clear: UPDATE animalcontroljob_progression SET timeout_until = NULL WHERE char_id = ?

---

HUD and NUI Issues

Timer Not Showing

1. Ensure the web UI was built: cd web && npm install && npm run build
2. Check that web/dist/index.html exists
3. Check F8 console for NUI errors

NUI Stuck Open

1. Press Escape to close
2. If cursor is stuck, restart the resource
3. As a last resort, reconnect to the server

---

Performance

Entity Cleanup

Restart the resource to trigger cleanup handlers. Vehicle, NPC, animal, prop, and bait entities are cleaned up on shift end, character unload, and resource stop.

Thread Optimization

Thread	Sleep Interval	Active During
Vehicle health monitor	1000ms	Any shift state
Animal behavior tick	100-2000ms	Active job with live animal
Bait ghost preview	0ms	Placing bait
Waypoint render	0ms	Waypoint visible (H held)
Call input listener	0ms	Incoming call notification

Threads automatically stop when not needed and restart on demand.

---

Debug Mode

Set Config.Debug = true in shared/config.lua and restart. Debug messages are prefixed with [oxide-animalcontroljob].

Logs include: shift state transitions, dispatch events, job completion/payment, crew events, progression changes, animal state transitions, bait/tranq events, vehicle health, NPC lifecycle, safety zones, and entity sync.

Debug Force Job Type

Config.DebugForceJobType = JobType.STRAY_CAPTURE  -- Only dispatch stray jobs

Set to nil for normal operation.

---

Getting Help

When reporting issues, include:

• Server framework (ESX, QBCore, QBX, etc.)
• community_bridge and ox_lib versions
• Vehicle model in use (default kennel or custom)
• Tranquilizer weapon in use (default WEAPON_G2 or custom)
• Error messages from server and client consoles
• Steps to reproduce
• Whether the issue occurs solo or in a crew
• Current shift state and job type
• Debug mode output if available

---

Next Steps

• Features — Understand all features and mechanics
• Configuration — Customize all settings
• Admin Tools — Admin commands
• Installation — Set up the resource