# Index

When something breaks, use these symptoms to find the cause and fix it quickly without guessing.

## Server Startup Failures

**Symptom:** Resource doesn't start; console shows Lua errors.

### Check Resource Order

VibesEZ-Race depends on executing AFTER its dependencies:

1. Stop the server.
2. Open `server.cfg`.
3. Ensure resource order:

   ```cfg
   ensure oxmysql
   ensure qb-core     # or qbx_core, es_extended
   ensure VibesEZ-Race
   ```
4. Start the server and check console again.

**If still broken:** Check the exact error message in console under `[VibesEZ-Race]` lines.

### Check Framework Detection

If framework not found:

1. Open `config/shared.lua`.
2. Verify framework name:

   ```lua
   Framework = 'auto'  -- or 'qbcore' | 'qbox' | 'esx' | 'custom'
   ```
3. Verify bridge resource names match your actual resources:

   ```lua
   Bridge = {
       qbResource = 'qb-core',    -- VERIFY: this is the actual resource folder name
       qboxResource = 'qbx_core', -- VERIFY: verify spelling
       esxResource = 'es_extended'
   }
   ```
4. Restart the resource.

## Database Issues

**Symptom:** Races don't save, profiles don't load, or console shows SQL errors.

### Verify Tables Exist

1. Open your MySQL client (PHPMyAdmin, Sequel Pro, etc.).
2. Run: `SHOW TABLES LIKE 'vibesez_race_%';`
3. Confirm these tables exist:
   * `vibesez_race_profiles`
   * `vibesez_race_roles`
   * `vibesez_race_tracks`
   * `vibesez_race_history`
   * `vibesez_race_chat_messages`
   * Any others shown in your output

**If tables are missing:**

1. Re-run the import:

   ```bash
   mysql -u your_user -p your_database < install/racing.sql
   ```
2. Restart the VibesEZ-Race resource.

### Check Table Names and Aliases

If tables exist but queries fail:

1. Open `config/shared.lua`.
2. Verify `Config.DatabaseTables` aliases match your actual table names.
3. If you renamed tables, update both config and `Config.Database.Tables` exports.

> **Warning:** Never rename `vibesez_race_*` tables in production without updating every alias. This breaks stat tracking.

### Check oxmysql Connection

If database connects but queries timeout:

1. Verify `oxmysql` is running: `ensure oxmysql` in server.cfg BEFORE `VibesEZ-Race`.
2. Check MySQL server is accessible from your game server's network.
3. Verify credentials in `oxmysql` resource config if using custom database.

## Permissions Not Working

**Symptom:** Staff commands denied for admins; wrong players see admin UI.

### Verify Master Admin Config

1. Open `config/shared.lua`.
2. Check `MasterAdmins.Mode`:

   ```lua
   MasterAdmins = {
       Mode = 'both',  -- identifier | framework | both
       Identifiers = {
           -- list of Discord or player identifiers
       },
       FrameworkGroups = { 'god', 'superadmin', 'admin' }  -- VERIFY: matches your framework groups
   }
   ```
3. For **identifier mode:** Add your Discord ID to the `Identifiers` table.
4. For **framework mode:** Ensure your account has a role matching `FrameworkGroups`.
5. Set `AdminMode.forceNonAdmin = false` (testing only; should be `false` in production).
6. Restart the resource and rejoin.

### Test Permission Nodes

1. With a staff account, open the admin panel.
2. Try to approve a track, edit roles, or moderate a player.
3. If denied: Check that role has `Config.Permissions` nodes assigned.

> **Tip:** Use `AdminMode.forceNonAdmin = true` temporarily to test non-admin access without losing your admin role.

## UI Not Loading

**Symptom:** Racing app crashes on open; shows error; or displays blank screen.

### Rebuild Web UI

1. Navigate to `VibesEZ-Race/web/`:

   ```bash
   cd VibesEZ-Race/web
   npm install
   npm run build
   ```
2. Verify `web/dist/index.html` exists.
3. Restart the VibesEZ-Race resource.

### Check Framework Identifier Resolution

If UI loads but profile shows empty:

1. Open `config/shared.lua`.
2. Verify framework identifier is being resolved:
   * QBCore: Should see `citizenid`
   * ESX: Should see `identifier`
   * Qbox: Should see `character_id`
3. Check server console for identifier resolution errors.

## Races Don't Save or Count

**Symptom:** Players complete races; results don't appear in profiles; leaderboard doesn't update.

### Verify Race Completion Flow

1. Complete a test race with 2+ players.
2. Check server console for completion callback logs.
3. Manually query the database:

   ```sql
   SELECT COUNT(*) FROM vibesez_race_history WHERE race_date > DATE_SUB(NOW(), INTERVAL 1 HOUR);
   ```
4. If count is 0: race aren't finishing; check race config.
5. If count > 0: races save but profiles might not refresh; restart resource.

### Check Race Finish Validation

If races complete but show wrong results:

1. Open `config/racing.lua`.
2. Verify `Racing.finishDetection.mode` matches your checkpoint design:

   ```lua
   finishDetection = {
       mode = 'checkpoint',  -- or 'location' if using map coordinates
       validateCheckpoints = true
   }
   ```
3. Re-test a full race.

## Performance Issues (FPS Drop, Lag)

**Symptom:** Frame rate drops during races; server CPU maxes out.

### Disable Non-Essential Features

1. Open `config/racing.lua`.
2. Disable GPS tracking if not needed:

   ```lua
   gpsTracker = {
       enabled = false  -- EDIT THIS
   }
   ```
3. Reduce racing line rendering:

   ```lua
   racingLine = {
       enabled = false  -- EDIT THIS if not needed
   }
   ```
4. Reduce checkpoint draw distance in track creator:

   ```lua
   creator = {
       previewDrawDistance = 300.0  -- EDIT THIS: lower = faster
   }
   ```
5. Restart and re-test.

### Monitor Expensive Operations

1. Check server console for repeated Lua errors (might cause CPU waste).
2. Limit concurrent races: Set race `maxPlayers` to your network capacity.
3. Monitor database query times: If queries timeout, increase oxmysql timeout in config.

## Chat Not Working

**Symptom:** Messages don't appear; filtering censors too aggressively; moderation doesn't trigger.

### Verify Chat is Enabled

1. Open `config/chat.lua`.
2. Check:

   ```lua
   Chat = {
       Enabled = true  -- EDIT THIS if false
   }
   ```
3. Restart the resource.

### Check Content Filter

If filtering is too strict:

1. Open `config/chat.lua`.
2. Review `ContentFilter.blockedPatterns`:

   ```lua
   blockedPatterns = {
       -- EDIT THIS: remove overly broad patterns
   }
   ```
3. Restart.

### Test Channel Visibility

If messages don't reach certain channels:

1. Open `config/chat.lua`.
2. Verify channel enable flags:

   ```lua
   Channels = {
       Global = { enabled = true },   -- EDIT THIS
       Crew = { enabled = true },     -- EDIT THIS
       etc...
   }
   ```
3. Restart and re-test.

## Common Questions

**Q: How do I apply config changes?** A: Edit the config file, then restart the VibesEZ-Race resource. Some changes require a full server restart (framework switches, oxmysql config).

**Q: How do I switch frameworks?** A: Open `config/shared.lua`, set `Framework`, update `Bridge` resource names, then restart the full server.

**Q: Can I rename database tables?** A: No. The system expects exact table names. If you must rename, update `Config.DatabaseTables` mapping for every affected query.

**Q: Do I need ox\_lib?** A: No, it's optional. If installed, set `useOxLibCallbacks` and `useOxLibNotify` to `true`. If not installed, leave them `false`.

## Next Steps

* **Performance Tuning:** See [Advanced Options](/vibesez/docs/advanced/overview.md)
* **Admin Moderation:** See [Moderation](/vibesez/docs/admin/moderation.md)
* **Getting Started:** [Returning to setup](https://github.com/VibesEZ/VibesEZ-Race/blob/claude-docs/docs/getting-started/README.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/troubleshooting/index.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.