Troubleshooting

Database Issues

Missing Tables

Symptoms:

• Startup errors mentioning vending_* tables
• Missing business, machine, or progression data

Checks:

SHOW TABLES LIKE 'vending_%';

Fix:

SOURCE sql/install.sql;

Progression Warning on Startup

Symptoms:

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

Checks:

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

If these tables are missing, rerun the install SQL.

Startup and Dependency Issues

Resource Fails to Start

Make sure startup order is:

ensure ox_lib
ensure oxmysql
ensure o-link
ensure oxide-vending

Then check:

• fxmanifest.lua is intact
• There are no syntax errors in edited Lua files
• o-link is returning valid modules for inventory, money, target, and framework lifecycle

Nil Access Through olink

Symptoms:

• attempt to index a nil value in oxide-vending scripts

Typical causes:

• o-link not started before oxide-vending
• o-link missing the module the resource expects
• Player-loaded lifecycle not firing because the framework bridge is not configured correctly

Business and Balance Issues

Registration Works but Balance Actions Fail

The resource uses its own business-side balance plus o-link.money for player bank interactions.

Checks:

1. Run:

   /vendingdebug bank [businessId]

2. Inspect the business row:

   SELECT business_id, balance FROM vending_businesses WHERE business_id = 'your-id';

3. Confirm the player has enough personal bank money for deposits.
4. Confirm the player has deposit or withdraw permission.

Revenue Seems Missing

Check both:

• Machine revenue and transactions
• The business balance on vending_businesses

If rows are correct in MySQL but the UI is stale, restart the resource to rebuild cache state.

Machine Issues

Placement Preview Does Not Appear

Checks:

1. Confirm the player is not in a vehicle.
2. Confirm the machine type exists in config/machines.lua.
3. Confirm the selected model is a valid GTA model.
4. Enable Config.Debug = true and retry.

Machine Cannot Be Placed

Common causes:

• The business has reached its current machine cap
• The machine type is still locked by progression
• The target location is inside a blocked zone
• The target location is too close to another machine
• The final position is farther than Config.Placement.MaxDistanceFromPlayer

Machine Does Not Interact

Checks:

1. Verify your target system is active through o-link.
2. Verify the machine status is active.
3. Check Config.Interaction.TargetDistance.
4. Check for overlapping third-eye targets from another resource.

Warehouse and Pickup Issues

Warehouse Code Does Not Work

Checks:

1. Confirm the business owns a warehouse:

   SELECT * FROM vending_warehouses WHERE business_id = 'your-id';

2. Confirm the code is the correct Config.Warehouse.CodeLength.
3. Remember that the entry event includes brute-force protection after repeated failed attempts.

Player Is Stuck in a Warehouse Bucket

Checks:

• Reconnect first
• Inspect current routing bucket state on the server
• If required, manually return the player to bucket 0

Warehouse Inventory Looks Wrong

Checks:

SELECT * FROM vending_business_inventory WHERE business_id = 'your-id';

Then confirm:

• Item names still exist in your inventory registry
• Config.Warehouse.MaxCapacity and MaxItemTypes are not blocking deposits
• There are no MySQL errors during deposit or withdrawal

Pickup Boxes Do Not Appear

Checks:

1. Confirm Config.PickupLocation.Enabled = true.
2. Confirm rows exist in vending_pickup_boxes.
3. Confirm the pallet coordinates and box models are valid for your map.
4. Use /vendingdebug boxes [count] to test the visual path.

NPC Sales Issues

No NPC Sales Are Being Generated

Checks:

1. Confirm Config.NPCSales.Enabled = true.
2. Run /vendingnpc stats.
3. Run /vendingnpc force to test the flow.
4. Confirm the machine is active.
5. Confirm the machine has stock.

NPC Sales Feel Too Low

Review:

• Machine type
• Location hotzone multiplier
• Current time multiplier
• Price competitiveness
• Stock variety
• Nearby competition penalties

Electronics machines in low-traffic areas with high markup will sell very slowly by design.

Time-of-Day Behavior Seems Wrong

The system first tries:

exports["oxide-weather"]:GetTime()

If that export is unavailable, it uses real server time. If you expect in-game time behavior, make sure oxide-weather is started and returning hour.

Progression Issues

Business Is Not Leveling

Leveling requires both:

• Enough XP
• Enough lifetime revenue

A business can be above the XP target and still stay at its current level if revenue has not reached the next milestone.

Missing Progression Row

Run:

/vendingdebug progression status
/vendingdebug progression init

or create one business manually:

/vendingdebug progression create <businessId>

Daily Bonus Is Inconsistent

The current implementation normalizes and compares dates in UTC. If your expectation is local-time rollover, the behavior can look early or late relative to local time.

Use:

/vendingdebug daily [businessId]

to inspect the cached and database date values.

Dashboard Issues

/vdb Opens Nothing

Checks:

1. Confirm the player owns a business or is an employee.
2. Check F8 for NUI errors.
3. Confirm the html/ files are present and not partially overwritten.
4. Confirm callbacks are registering without server errors.

Dashboard Opens but Shows Empty or Broken Data

Checks:

• Server callback errors
• MySQL connectivity
• Stale or missing business rows
• Missing map tile assets under html/img/map-tiles/

Performance Issues

Server-Side Load

Possible mitigation:

• Raise Config.NPCSales.TickInterval
• Reduce Config.Transactions.RetentionDays
• Keep Config.Transactions.PruneOnStartup = true
• Reduce competition-heavy dense machine clusters

Client FPS Drops Near Machine Clusters

Possible causes:

• Too many machines in one area
• Heavy nearby ambient-ped animation from NPC visual feedback
• Expensive prop choices

Common Errors

"Machine type not unlocked"

The business level has not unlocked that category yet.

"Maximum machines reached"

The business is at its current machine limit.

"Server business limit reached"

Config.Business.MaxBusinesses has been reached.

"Item not allowed in this machine type"

The item is not listed in the machine type whitelist.

"Price out of range"

The entered price is outside the current allowed pricing range for that business and item.

"Rate limited" or similar anti-spam errors

The action is hitting the server-side limiter. If this is happening during normal play, review the rate-limit values in server/main.lua.

Debug Mode

Enable:

Config.Debug = true

This adds useful logging for:

• Cache loading
• Placement flow
• Machine sync
• Progression and milestones
• NPC sales
• Warehouse and pickup operations

Next Steps

• Installation Guide
• Configuration
• Admin Commands

Support

Need more help?

• Discord: https://discord.gg/dZ6q8FyGhm
• Website: https://www.oxidestudios.dev/
• o-link (required abstraction layer): https://github.com/WHEREISDAN/o-link