Troubleshooting

Solutions for common issues with oxide-blackmarket.

---

Dealer Issues

Dealer Not Spawning

Symptoms:

• No dealer visible anywhere
• /dealerstatus shows "No dealer currently active"

Solutions:

1. Check console for errors

   Look for: [oxide-blackmarket] ERROR: Failed to create dealer ped

2. Verify dependencies are running

   # server.cfg - Ensure correct order
   ensure qb-core
   ensure qb-target
   ensure qb-inventory
   ensure oxide-blackmarket

3. Check OneSync is enabled

   set onesync on

4. Force respawn

   /relocatedealer

5. Check resource is started

   Look for: [oxide-blackmarket] Resource starting...

---

Dealer Not Visible to Players

Symptoms:

• Dealer spawns but some players can't see it
• /godealer works but dealer invisible

Solutions:

1. Verify OneSync culling radius

   • The resource sets 50km culling radius automatically
   • Ensure no other scripts are modifying entity culling

2. Check network sync

   -- Debug: Enable in config
   Config.Debug = true
   -- Look for: Notifying all clients of dealer spawn

3. Player may need to re-stream

   • Have player move closer to spawn location
   • Or restart their game

---

Dealer Gets Stuck

Symptoms:

• Dealer doesn't wander
• Dealer stuck in geometry

Solutions:

1. Force relocation

   /relocatedealer

2. Adjust spawn locations

   • Check Config.Locations for problematic spots
   • Ensure locations are in open areas
   • Test each location manually

3. Check for pathfinding issues

   • Avoid indoor locations
   • Avoid areas with complex geometry

---

Shop Issues

Shop Not Opening

Symptoms:

• Target shows interaction but nothing happens
• No shop UI appears

Solutions:

1. Check qb-target is working

   • Test other qb-target interactions
   • Restart qb-target resource

2. Verify dealer is tradable

   • Dealer becomes untradable if damaged
   • Use /relocatedealer to reset

3. Check NUI

   • Press F8 and check for JavaScript errors
   • Verify html/ folder exists with all files

4. Check debug output

   -- Enable debug and look for:
   -- 'Requesting shop from server'
   -- 'Shop request from player X'

---

Transaction Failing

Symptoms:

• Buy/sell button doesn't work
• "Transaction failed" message

Solutions:

1. Check player has enough money/items

   • Verify cash for purchases
   • Verify item exists in inventory for sales

2. Check dealer still exists

   • Dealer may have been killed/relocated mid-transaction
   • Close shop and re-open

3. Check stock availability

   • Item may be out of stock
   • Stock resets on relocation

4. Check inventory space

   • Player may have full inventory
   • Make room and try again

---

Items Not Appearing in Shop

Symptoms:

• Shop opens but items are missing
• Only some tiers showing

Solutions:

1. Check player reputation tier

   /checkblackmarketrep [playerID]

   • Items only show for current tier and below

2. Verify item definitions

   • Check shared/items.lua for correct format
   • Ensure items exist in qb-core/shared/items.lua

3. Check tier configuration

   -- Verify Config.ShopInventory[tier] exists
   -- Verify items have all required fields

---

Police Mechanic Issues

Dealer Not Surrendering

Symptoms:

• Aiming at dealer does nothing
• Dealer doesn't put hands up

Solutions:

1. Verify player is police

   -- Job type must be 'leo'
   -- Check: PlayerData.job.type == 'leo'

2. Check aim distance

   • Must be within 15m (Config.AimSurrenderDistance)
   • Must be actively aiming (not just holding weapon)

3. Dealer already broken out

   • If dealer broke free once, they won't surrender again
   • Wait for relocation or use /relocatedealer

4. Dealer already dead or damaged

   • Damaged dealers fight, don't surrender

---

Arrest Not Working

Symptoms:

• [E] prompt appears but arrest fails
• Arrest animation plays but nothing happens

Solutions:

1. Verify dealer is surrendered

   • Dealer must have hands up
   • Must be within 10-second window

2. Check distance

   • Must be within 5m (Config.ArrestDistance)

3. Dealer broke free

   • If 10-second timer expired, dealer attacks
   • Cannot arrest hostile dealer

4. Check police job

   • Must have job.type == 'leo'

---

Dealer Fleeing Too Often

Symptoms:

• Dealer keeps running away
• Can't complete arrest

Solutions:

1. Stay close to dealer

   • Stay within 8m (Config.FleeDistanceThreshold)
   • Don't back away while dealer is surrendered

2. Adjust flee settings

   -- Reduce flee chance
   Config.FleeChance = 0.20  -- 20% instead of 35%
   
   -- Or increase threshold
   Config.FleeDistanceThreshold = 12.0

---

Hit Squad Issues

Hit Squad Not Spawning

Symptoms:

• Kill dealer but no retaliation
• No vehicle spawns

Solutions:

1. Verify hit squad is enabled

   Config.HitSquadEnabled = true

2. Check if player damaged dealer

   • Hit squad only targets player who damaged/killed
   • Other players won't trigger squad

3. Check debug output

   Look for: 'Spawning hit squad...'
   Look for: 'No ideal node found'

4. Check spawn location

   • May fail in remote areas with no road nodes
   • Try in city areas

---

Hit Squad AI Issues

Symptoms:

• Squad spawns but doesn't attack
• Squad gets stuck

Solutions:

1. Check difficulty settings

   Config.HitSquadDifficulty = 'medium'
   -- Try 'easy' for testing

2. Verify vehicle spawned

   • Vehicle may have failed to spawn
   • Check if model exists

3. Check combat ability

   Config.HitSquadCombatAbility = {
       easy = 50,
       medium = 75,
       hard = 100,
   }

---

Pager Issues

Pager Not Working

Symptoms:

• Use pager, nothing happens
• No notification

Solutions:

1. Check tier requirement

   • Must be Tier 2 or higher

   /checkblackmarketrep [playerID]

2. Check cooldown

   • 5-minute cooldown between uses
   • Wait and try again

3. Verify item exists

   • Check qb-core/shared/items.lua for blackmarket_pager
   • Verify item is useable

4. Check dealer exists

   • Pager fails if no dealer active

   /dealerstatus

---

Pager Email Not Received (Tier 4)

Symptoms:

• Pager works but no email
• Only get notification, no waypoint

Solutions:

1. Verify qb-phone is installed

   • Email feature requires qb-phone
   • Check resource is running

2. Check phone has correct export

   -- Uses: exports['qb-phone']:sendNewMailToOffline

3. Verify Tier 4

   • Email only sent at Tier 4 (1000+ rep)
   • Lower tiers get area name only

---

Blip Issues

Blips Not Appearing

Symptoms:

• Get close to dealer but no blip
• Blip system seems broken

Solutions:

1. Check detection range

   • Must be within 200m (Config.BlipDetectionRange)

2. Check cooldown

   • 2-minute cooldown between flashes
   • Wait and approach again

3. Verify blips.lua is loaded

   • Check fxmanifest.lua includes blips.lua
   • Check for errors in console

4. Check debug output

   Look for: [oxide-blackmarket:blips] messages

---

Loot Issues

Loot Bag Not Appearing

Symptoms:

• Dealer dies but no loot bag
• Can't find loot

Solutions:

1. Verify loot is enabled

   Config.LootDropEnabled = true

2. Check model loading

   Look for: 'Failed to load loot bag model'

3. Check death coords

   Look for: 'Death coords missing or invalid'

---

Can't Collect Loot

Symptoms:

• Loot bag visible but can't interact
• Search animation plays but nothing received

Solutions:

1. Check qb-target interaction

   • Verify bag is targetable
   • Try from different angle

2. Loot already collected

   • First-come-first-served
   • Another player may have collected

3. Check proximity

   • Must be within 5m of bag
   • Move closer and try again

4. Check debug output

   Look for: 'CollectLoot: Player X too far'

---

Performance Issues

High CPU Usage

Solutions:

1. Reduce check intervals

   Config.FleeCheckInterval = 2000       -- 2 sec instead of 1
   Config.HitSquadCheckInterval = 2000   -- 2 sec instead of 1

2. Reduce detection range

   Config.BlipDetectionRange = 150.0     -- 150m instead of 200

3. Disable debug mode

   Config.Debug = false

---

Network Desync

Solutions:

1. Check server tick rate

   • Ensure adequate server performance

2. Reduce culling radius (not recommended)

   • Currently set to 50km for visibility
   • Only reduce if necessary

---

Debug Mode

Enable comprehensive logging:

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

Console output includes:

• Dealer spawn/despawn events
• Shop requests and transactions
• Reputation changes
• Hit squad spawning
• Loot generation
• Pager usage

Log prefix: [oxide-blackmarket]

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 errors
4. Verify all dependencies are latest versions
5. Test with minimal resources to isolate conflicts

Need more help? Join our Discord server for support.