Troubleshooting

Database Issues

Tables Not Created

Symptom: Errors about missing tables on startup.

Solution:

1. Run sql/install.sql in your database
2. Verify tables exist:

   SHOW TABLES LIKE 'vending_%';

3. Check MySQL permissions

Progression Table Missing

Symptom: [oxide-vending] WARNING: Could not load progression data

Solution:

1. The progression tables are included in sql/install.sql
2. If upgrading from older version, verify tables exist:

   SELECT * FROM vending_progression LIMIT 1;
   SELECT * FROM vending_milestones LIMIT 1;

Foreign Key Errors

Symptom: Cannot add or update a child row: a foreign key constraint fails

Solution:

1. Delete data in child tables first
2. Or use SET FOREIGN_KEY_CHECKS = 0; temporarily
3. Ensure parent records exist before creating children

---

Resource Startup Issues

Resource Won't Start

Symptom: Resource fails to start or immediately stops.

Checklist:

1. Verify all dependencies are started first. The required resources depend on your framework:
   • Always required: oxmysql, ox_lib
   • QBCore: qb-core, qb-target, qb-inventory, qb-radialmenu, qb-input
   • QBx: qbx_core, ox_target, ox_inventory
   • ESX: es_extended, ox_target, optionally ox_inventory
   • Standalone: ox_inventory, ox_target
2. Check for Lua syntax errors in server console
3. Verify fxmanifest.lua is valid

Dependencies Not Found

Symptom: SCRIPT ERROR: @oxide-vending/...lua: attempt to index a nil value

Solution:

1. Check the server console for the bridge detection message to confirm which framework was detected
2. Ensure your framework's core resource is starting before oxide-vending
3. Check resource start order in server.cfg
4. If auto-detection fails, try setting Config.BridgeOverride in config/config.lua

---

Framework Bridge Issues

Framework Not Detected

Symptom: Bridge falls back to standalone when you expected QBCore/ESX.

Solution:

1. Ensure your framework resource is started before oxide-vending in server.cfg
2. Check that the framework resource name matches what the bridge expects (qb-core, qbx_core, es_extended)
3. Set Config.BridgeOverride in config/config.lua to force the correct framework

Standalone Items Not Loading

Symptom: Items list is empty or QBCore.Shared.Items has no entries in standalone mode.

Solution:

1. Verify ox_inventory is started and has items configured
2. Check that Config.StandaloneInventory.GetItemList returns the correct item registry
3. Items are synced to clients via the oxide-vending:bridge:syncItems event on player load

ESX Inventory Operations Failing

Symptom: Players can't stock/purchase items on ESX.

Solution:

1. ox_inventory is auto-detected when running — no manual config needed
2. Check that your inventory resource is started before oxide-vending
3. Verify items exist in your inventory system's item registry

---

Warehouse Issues

Warehouse Access Code Not Working

Symptom: Can't enter warehouse with correct code.

Checklist:

1. Verify business owns a warehouse: check vending_warehouses table
2. Ensure business level meets Config.Warehouse.RequiredLevel
3. Check bucket ID assignment in server console

Stuck in Warehouse Instance

Symptom: Player can't leave warehouse or is in wrong routing bucket.

Solution:

1. Reconnecting should restore the player to the normal world
2. Check PlayerBuckets cache in server for the player's current bucket
3. As a last resort, admin can use SetPlayerRoutingBucket to return player to bucket 0

Warehouse Inventory Missing

Symptom: Items added to warehouse don't appear.

Checklist:

1. Check vending_business_inventory table in database
2. Verify BusinessInventory cache is in sync
3. Check server console for MySQL errors during warehouse operations

---

Machine Issues

Machines Not Spawning

Symptom: Placed machines don't appear in-game.

Checklist:

1. Check Config.Debug = true for spawn logs
2. Verify machine coords in database are valid
3. Check for model streaming issues:

   -- In client console
   local model = GetHashKey('prop_vend_soda_01')
   print('Model valid:', IsModelValid(model))

4. Ensure player is in range for entity spawning

Machine Placement Fails

Symptom: Can't place machines, preview doesn't appear.

Checklist:

1. Verify player has a business
2. Check machine limit (GetMaxMachines)
3. Ensure machine type is unlocked
4. Check for blocked zones
5. Verify minimum distance from other machines

Interaction Not Working

Symptom: Can't interact with placed machines.

Checklist:

1. Verify your target resource is running (qb-target for QBCore, ox_target for QBx/ESX/Standalone)
2. Check interaction distance in config
3. Ensure machine status is active
4. Check for conflicting target zones

---

Banking Issues

Revenue Not Depositing

Symptom: Revenue collected but money not received.

Diagnosis:

/vendingdebug bank [businessId]

Common causes:

1. oxide-banking not started
2. Business account doesn't exist
3. Owner offline (fallback mode)

Business Account Missing

Symptom: ACCOUNT NOT FOUND in debug output.

Solution:

1. Check account name format: vending-{business_id}
2. Manually create account in oxide-banking
3. Or disable Config.UseBanking to use fallback

Fallback Mode Issues

Symptom: Banking works but requires owner online.

Explanation: Without oxide-banking:

• Revenue goes to owner's QB bank account
• Owner must be online for some operations
• Consider installing oxide-banking for full functionality

---

NPC Sales Issues

NPC Sales Not Generating

Symptom: No NPC sales appearing in transactions.

Checklist:

1. Verify NPC sales enabled: /vendingnpc toggle
2. Check machine has stock
3. Check machine status is active
4. Force a tick: /vendingnpc force
5. Check Config.NPCSales.Enabled

Low NPC Revenue

Symptom: NPC sales are rare or low value.

Consider:

1. Machine location (check hotzones)
2. Time of day (night = low sales)
3. Machine type (electronics = rare)
4. Price competitiveness (high markup = fewer sales)
5. Stock availability (empty slots = lower multiplier)
6. Competition (nearby cheaper machines)

NPC Sales Stats Show Zero

Symptom: /vendingnpc stats shows 0 sales.

Note: Stats reset on resource restart. This is expected behavior.

---

Progression Issues

Progression Not Tracking

Symptom: XP and level not updating.

Checklist:

1. Verify Config.Progression.Enabled = true
2. Check if business has progression record:

   /vendingdebug progression status

3. Create missing records:

   /vendingdebug progression init

Business Stuck at Level 1

Symptom: Has enough XP but won't level up.

Explanation: Level up requires BOTH:

• XP threshold met
• Revenue milestone met

Check both values in progression data.

Daily Bonus Not Working

Symptom: Can't claim daily bonus or streak resets.

Diagnosis:

/vendingdebug daily [businessId]

Common issues:

1. Already claimed today (check date comparison)
2. Timezone issues (uses UTC internally)
3. Database date format mismatch

Milestones Not Triggering

Symptom: Reached milestone value but no XP bonus.

Possible causes:

1. Milestone already claimed (check vending_milestones table)
2. Progression notifications disabled
3. Value crossed during offline period

---

Dashboard Issues

Dashboard Won't Open

Symptom: /vdb command does nothing.

Checklist:

1. Verify player has business or is employee
2. Check for NUI errors in F8 console
3. Verify HTML files exist in html/ directory
4. Check for JavaScript errors in browser console

Dashboard Shows No Data

Symptom: Dashboard opens but displays blank.

Checklist:

1. Check server callbacks are registered
2. Verify database connectivity
3. Check for Lua errors in server console
4. Ensure business has data to display

Map Not Displaying

Symptom: Map tab shows no machines or broken image.

Checklist:

1. Verify html/img/gta-map.png exists
2. Check machine has valid coordinates
3. Verify coordinate conversion is correct

---

Performance Issues

Server Lag

Symptom: Server performance drops with oxide-vending.

Optimization tips:

1. Increase Config.NPCSales.TickInterval
2. Reduce transaction history RetentionDays
3. Enable transaction pruning
4. Check for runaway loops in console

Client FPS Drops

Symptom: FPS drops near vending machines.

Possible causes:

1. Too many machines in small area
2. Complex models streaming
3. Dashboard open with lots of data

---

Common Error Messages

"You do not have access to a vending business"

Player is not an owner or employee of any business.

"Machine type not unlocked"

Business level too low for that machine type. Check Progression for unlock requirements.

"Maximum machines reached"

Business has reached its machine limit for current level.

"Not enough money"

Player or business account lacks funds for purchase.

"Item not allowed in this machine type"

Item is not in the whitelist for that machine type.

"Price out of range"

Set price is below minimum or above maximum markup for the item.

"Rate limited" / "Too many requests"

Player is performing actions too quickly. All actions have configurable cooldowns and window-based limits. Wait a moment and try again. If this happens frequently during normal use, consider adjusting RateLimitConfig values in server/main.lua.

---

Debug Mode

Enable debug logging for detailed information:

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

This adds verbose logging for:

• Machine spawning/despawning
• NPC sales simulation
• Cache operations
• Progression changes

---

Getting Help

If issues persist:

1. Check server console for errors
2. Check F8 client console for errors
3. Enable Config.Debug = true
4. Check database for data integrity
5. Verify all dependencies are correct versions