# Troubleshooting

Solutions for common VibesEZ-Laptop issues on your server.

## Installation Issues

### Resource Won't Start

**Symptom:** Resource appears offline in console

**Checklist:**

```
☐ File structure correct?
☐ All files present?
☐ fxmanifest.lua valid Lua?
☐ oxmysql loaded first?
☐ No syntax errors in config?
☐ Permission issues?
```

**Solutions:**

1. **Check fxmanifest.lua**

   ```bash
   lua -c fxmanifest.lua  # Validate syntax
   ```
2. **Verify load order** in server.cfg

   ```lua
   ensure oxmysql           # Must be first
   ensure qb-core          # Second
   ensure VibesEZ-Laptop   # Third
   ```
3. **Check file permissions**

   ```bash
   chmod -R 755 VibesEZ-Laptop/
   ```
4. **Review console errors**
   * Look for specific error messages
   * Search documentation for error
   * Report with full error message

***

## Database Issues

### Database Connection Failed

**Symptom:** "Cannot connect to database" error

**Troubleshooting:**

1. **Verify oxmysql is running**

   ```
   Console output: oxmysql started? ✓
   ```
2. **Check connection credentials**
   * Host: correct server
   * Port: correct port (usually 3306)
   * Username: correct user
   * Password: correct password
   * Database: exists?
3. **Test MySQL connection manually**

   ```bash
   mysql -h localhost -u user -p -D database_name
   ```
4. **Check firewall**
   * Port 3306 open?
   * Blocked by firewall?
   * Security group rules?
5. **Restart oxmysql**

   ```
   Stop server → Restart → Check connection
   ```

### Database Tables Missing

**Symptom:** "Table not found" errors

**Solution:**

1. Verify SQL import ran

   ```bash
   mysql -h host -u user -p database < install/vibesez_crypto.sql
   ```
2. Check imported tables

   ```sql
   SHOW TABLES LIKE 'crypto_%';
   ```
3. Reimport if needed

   ```bash
   # Backup first!
   mysql -h host -u user -p database < install/vibesez_crypto.sql
   ```

***

## Wallet & Crypto Issues

### Wallets Not Creating

**Symptom:** Player opens crypto app, no wallets shown

**Investigation:**

1. **Check wallet creation logs**

   ```lua
   -- Check server logs for wallet creation errors
   ```
2. **Test manual wallet creation**

   ```lua
   exports['VibesEZ-Laptop']:AddCrypto(identifier, 'BTC', 100, 'test')
   ```
3. **Verify database permissions**
   * User can insert rows?
   * Table exists and is accessible?
   * No quota limits?
4. **Check player identifier**
   * Is it valid?
   * Is it consistent?
   * Does it match database?

**Solutions:**

* Restart resource: `refresh VibesEZ-Laptop`
* Reset player data (if necessary)
* Check database directly for old data

### Transfer Stuck in Pending

**Symptom:** Transfer shows "Pending" indefinitely

**Possible Causes:**

* Network issue
* Database timeout
* Server crash mid-transfer
* Corrupted transaction record

**Recovery:**

1. **Wait 5 minutes**
   * Sometimes completes with delay
2. **Check transaction in database**

   ```sql
   SELECT * FROM crypto_transactions
   WHERE status = 'pending'
   LIMIT 10;
   ```
3. **Manual confirmation** (if necessary)

   ```sql
   UPDATE crypto_transactions
   SET status = 'confirmed'
   WHERE id = transaction_id;
   ```
4. **Restart resource** if many pending
   * Back up database first
   * Document incident
   * Monitor for recurrence

### Balance Mismatch

**Symptom:** Player balance doesn't match transaction history

**Investigation:**

1. **Sum transactions manually**

   ```sql
   SELECT SUM(amount) FROM crypto_transactions
   WHERE receiver = 'player_id' AND status = 'confirmed';
   ```
2. **Compare to stored balance**
   * Should match
   * If not, database corruption possible
3. **Check for pending transfers**
   * Pending not included in balance?
   * Check logic in config

**Resolution:**

1. **Audit transaction history**
   * Export all transactions
   * Manual verification
   * Document discrepancy
2. **Correct balance if authorized**

   ```lua
   exports['VibesEZ-Laptop']:SetBalance(identifier, currency, amount)
   ```
3. **Monitor for recurrence**
   * Set up database integrity checks
   * Regular audits
   * Alert on discrepancies

***

## Transfer Issues

### Transfer Failed - Insufficient Funds

**Symptom:** Transfer rejected with insufficient balance

**Check:**

* Actually have balance? (check app shows correctly)
* Account for fees? (balance >= amount + fee)
* Pending transactions? (not reflected in available?)

**Solution:** Verify balance first, ask player to wait for pending transfers

### Transfer Failed - Invalid Address

**Symptom:** "Invalid recipient address" error

**Verify:**

* Address format correct?
* Player name correct?
* Address exists?
* Typo in address?

**Help Player:**

* Copy-paste instead of typing
* Use contact list if available
* Verify with recipient

### Transfer Fee Higher Than Expected

**Symptom:** Player paid unexpected fees

**Check:**

* What's your fee configuration?
* Is it shown before transfer?
* Any server-specific fees?

**Resolution:**

* If clearly wrong, reverse transfer
* Explain fee structure to player
* Document for future reference

***

## App Issues

### Built-in App Crashes

**Symptom:** App closes when opened

**Troubleshooting:**

1. **Check browser console** (if NUI-based)
   * JavaScript errors?
   * Network requests failing?
   * Resource not loading?
2. **Restart laptop** (user action)
   * Close laptop
   * Wait 5 seconds
   * Reopen
3. **Restart resource** (server action)

   ```
   refresh VibesEZ-Laptop
   ```
4. **Check for conflicts**
   * Other resources interfering?
   * Modified files?
   * Wrong version?

### Storage Issues

**Symptom:** Not enough storage space

**Causes:**

* Too many apps installed
* Large app files
* User cache accumulation

**Solutions:**

1. **Verify storage**
   * Player storage not full?
   * Server storage not full?
2. **Force reinstall**
   * Uninstall completely
   * Clear cache
   * Reinstall
3. **Check app integrity**
   * Is app file corrupted?
   * Re-upload from source

***

## Performance Issues

### Server FPS Drops with Laptop Open

**Symptom:** FPS significantly lower when laptop UI loaded

**Investigation:**

1. **Profile the resource**
   * Check CPU usage by resource
   * Look for memory leaks
   * Monitor database queries
2. **Check for specific apps**
   * Does it happen with all apps?
   * Specific app causes it?
   * UI rendering issue?
3. **Player count correlation**
   * Happens with many players?
   * More laptops open = worse?
   * Database bottleneck?

**Solutions:**

* Optimize UI rendering settings (disable animations)
* Check database connection pool size
* Reduce player limit temporarily
* Update to latest version (if bug fix available)

### Slow Database Queries

**Symptom:** "Query timeout" errors, transactions take too long

**Diagnosis:**

```sql
-- Show slow queries
SHOW VARIABLES LIKE 'long_query_time';
SELECT * FROM mysql.slow_log;
```

**Optimization:**

1. Add database indexes
2. Archive old data
3. Increase pool size
4. Optimize queries
5. Upgrade server resources

### High Memory Usage

**Symptom:** Server memory filled up, growing resource

**Investigation:**

* Memory leak in resource?
* Too many cached items?
* Player data not being cleaned?

**Solutions:**

* Restart resource if necessary
* Clear caches: `refresh VibesEZ-Laptop`
* Check for memory leak in recent updates
* Review player limits

***

## UI/Display Issues

### Laptop UI Won't Load

**Symptom:** Blank screen when opening laptop

**Troubleshooting:**

1. **Check browser console** for NUI errors
2. **Verify web files** are in correct location
3. **Clear cache** - restart laptop
4. **Check browser** - right error loading?
5. **Restart client** if necessary

### UI Freezes or Unresponsive

**Causes:**

* JavaScript error
* Server lag affecting UI
* NUI focus lock
* Browser bottleneck

**Solutions:**

* Press ESC to close laptop
* Wait 10 seconds
* Reopen laptop
* Restart client if persists

### Wrong Colors/Theme Not Applying

**Check:**

* Settings saved correctly?
* Cache cleared?
* Multiple tabs/instances open?
* Theme override in config?

**Solution:**

* Close & reopen laptop
* Clear browser cache
* Restart client

***

## Security Issues

### Suspected Unauthorized Transfer

**Response Protocol:**

1. **Do not panic** - document everything
2. **Immediately disable transfers** → restart resource with transfers disabled
3. **Audit transaction** - verify legitimacy
4. **Check logs** - who initiated transfer?
5. **Interview players** - verify story
6. **Review security** - how was account accessed?
7. **Take action** - reverse if confirmed fraud
8. **Communicate** with player and GM team

**Prevention:**

* Enable 2FA
* Log all sensitive operations
* Regular security audits
* Educate players on security

### Account Compromise

**If Player Account Compromised:**

1. **Secure account** - prevent further damage
2. **Audit activity** - what happened?
3. **Restore wallet** - from backup if available
4. **Change credentials** - force password reset
5. **Enable 2FA** - prevent recurrence
6. **Communicate** with player
7. **Investigate root cause** - how was account accessed?

***

## Common Error Messages

### "Wallet initialization failed"

* **Cause:** Database issue, identifier problem
* **Fix:** Restart resource, check database

### "Transfer verification timeout"

* **Cause:** Network issue, database slow
* **Fix:** Retry, check database performance

### "Insufficient balance"

* **Cause:** Not enough funds or pending transfers
* **Fix:** Verify balance, wait for pending transfers

### "Invalid transaction format"

* **Cause:** Data corruption, incorrect entry
* **Fix:** Manual correction in database if needed

### "Permission denied"

* **Cause:** Player lacks permission for action
* **Fix:** Check configuration, admin approval

***

## Getting Help

### Before Contacting Support

Prepare:

* [ ] Full error message
* [ ] Steps to reproduce
* [ ] Server specifications
* [ ] Configuration files (sanitized)
* [ ] Recent log files
* [ ] When it started happening

### Support Resources

* Check this documentation
* Search community forums
* Review GitHub issues
* Contact developers
* Report in Discord

***

For more help, see [Installation](https://github.com/VibesEZ/VibesEZ-Laptop/blob/main/docs/admin/installation.md) or [Configuration](https://github.com/VibesEZ/VibesEZ-Laptop/blob/main/docs/admin/configuration.md).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://vibesez.gitbook.io/vibesez/docs/laptop/for-administrators/troubleshooting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.