⚠️Troubleshooting

This guide helps resolve common issues with the DevHub Racing script based on configuration and setup.

Resource Not Starting

Check Dependencies

Problem: Resource fails to start or shows errors in console.

Solution:

1. Ensure devhub_lib is started before this resource:

   -- server.cfg
   ensure devhub_lib
   ensure devhub_laptop
   ensure devhub_racing

2. If skill tree is enabled, ensure devhub_skillTree is started before:

   -- server.cfg
   ensure devhub_lib
   ensure devhub_skillTree
   ensure devhub_laptop
   ensure devhub_racing

3. Check for SQL errors - ensure database tables are created:

   • Import sql.sql file into your database

   • Verify tables exist: devhub_racing_maps, devhub_racing_users, devhub_racing_races, etc.

Verify Config Syntax

Problem: Script stops loading or throws Lua errors.

Solution:

1. Check all config files for syntax errors:

   • Missing commas in tables

   • Mismatched brackets {}, []

   • Unclosed strings ""

   • Invalid Lua syntax

2. Use a Lua syntax validator or IDE with Lua support to check files.

Check File Permissions

Problem: Resource cannot read configuration files.

Solution:

1. Ensure all files in configs/ folder have read permissions.

2. On Linux servers, check file ownership:

   chown -R fivem:fivem /path/to/devhub_racing
   chmod -R 755 /path/to/devhub_racing

---

Players Cannot Use the System

Check Entry Fee Requirements

Problem: Players cannot join races despite having money.

Solution:

1. Verify payment method configuration in configs/sh.config.lua:

   Config.EntryFeePaidVia = 'cash'  -- or 'bank'

2. Ensure players have money in correct account:

   • 'cash' = money on hand

   • 'bank' = bank account balance

3. Ensure you have correctly configured devhub_lib (NEEDED FOR EACH SCRIPT!)

Verify Vehicle Class Skills

Problem: Players get "must unlock class skill" error.

Solution:

1. Check if skill tree is enabled in configs/sh.config.lua:

   Config.SkillTreeEnabled = false  -- Set to false to disable requirement

2. If skill tree enabled, ensure players have unlocked required class:

   • Class C: Starting class (should be auto-unlocked)

   • Classes B, A, S: Must be unlocked via skill tree

3. Grant skill points to players for testing:

   • Use skill tree admin commands

   • Or temporarily disable: Config.SkillTreeEnabled = false

Check Vehicle Class Restrictions

Problem: "Your vehicle is not allowed in this race" error.

Solution:

1. Verify vehicle is in correct class in configs/c.vehicleClasses.lua:

   Config.VehicleClasses = {
       S = { `adder`, `zentorno`, ... },
       -- Add custom vehicles here
   }

2. Check if race has "ALL" class selected (allows any vehicle).

3. Debug vehicle hash:

   • Enable debug mode: Config.Debug = true

   • Check console for vehicle model hash when attempting to join

   • Add hash to appropriate vehicle class

Verify Coordinates and Positions

Problem: Players spawn in wrong locations or checkpoints don't work.

Solution:

1. Ensure map has valid coordinates:

   • Start position set

   • Finish position set

   • At least one checkpoint configured

2. Check map in database for corrupted data:

   SELECT * FROM devhub_racing_maps WHERE id = YOUR_MAP_ID;

3. Recreate map if coordinates are invalid:

   • Delete problematic map

   • Create new map with map creator

   • Test thoroughly before making official

Check Admin Permissions

Problem: Players cannot create maps/races despite being admin.

Solution:

1. Verify admin permissions in configs/sh.config.lua:

   Config.IsAdminPermissionRequired = {
       ['verifyMap'] = true,  -- Only admins can verify
       ['createMap'] = false,  -- Anyone can create
       ['createRace'] = false,  -- Anyone can create
       ['editMap'] = false,  -- Users can edit own maps
       ['editAnyMap'] = true,  -- Only admins edit any map
   }

2. Ensure devhub_lib (NEEDED FOR EACH SCRIPT!) recognizes player as admin:

   • Check admin system in your framework

   • Test with: Core.IsPlayerAdmin(source) function

   • Verify ace permissions

---

Features Not Triggering

Verify Callback Functions

Problem: Custom integrations don't execute.

Solution:

1. Check callback functions in configs/c.functions.lua and configs/s.functions.lua:

   OpenClientFunctions = {
       CanJoinRace = function(raceData)
           -- Must return true/false
           return true
       end,
       RaceFinish = function(activeRaceData, position, finishData)
           -- Your custom code here
           return  -- Must have return statement
       end,
   }

2. Ensure functions don't have errors:

   • Check F8 console for client errors

   • Check server console for server errors

   • Add debug prints to verify execution

3. Common mistakes:

   -- WRONG: No return value
   CanJoinRace = function(raceData)
       print("Checking...")
       -- Missing return true
   end
   
   -- CORRECT:
   CanJoinRace = function(raceData)
       print("Checking...")
       return true  -- Must return boolean
   end

Check Event Probability Tables

Problem: Rewards or MMR not being awarded.

Solution:

1. Verify reward tables in configs/sh.config.lua:

   Config.MmrForWin = {
       [1] = 50,  -- Must be > 0
       [2] = 25,
       [3] = 10,
   }
   Config.MmrForLost = -25  -- Can be negative

2. Check if MMR is enabled for race type:

   Config.AllowMrrOnAllRaces = false  -- Only official races award MMR
   -- OR
   Config.AllowMrrOnAllRaces = true  -- All races award MMR

3. Verify XP table (if skill tree enabled):

   Config.XpForFinishingRace = {
       [1] = 100,
       [2] = 50,
       -- ... not empty or zero
   }

Ensure Config Values Are Valid

Problem: Features behave unexpectedly or don't work.

Solution:

1. Check for empty or invalid config values:

   -- WRONG: Empty table
   Config.MmrForWin = {}
   
   -- WRONG: Nil value
   Config.DefaultMmr = nil
   
   -- CORRECT:
   Config.MmrForWin = { [1] = 50, [2] = 25, [3] = 10 }
   Config.DefaultMmr = 1000

2. Verify data types:

   • Numbers: 1000, 50.5, -25

   • Strings: "cash", "ALL"

   • Booleans: true, false

   • Tables: {}, { key = value }

3. Check for typos in config keys:

   -- WRONG: Typo in property name
   Config.DefautMmr = 1000  -- Should be "DefaultMmr"
   
   -- CORRECT:
   Config.DefaultMmr = 1000

---

Props, UI and Events Not Working

Verify Prop Models Exist

Problem: Props don't appear in map creator or during races.

Solution:

1. Check prop model names in configs/c.creatorProps.lua:

   {
       image = "https://...",
       prop = "prop_beachflag_01",  -- Must be valid GTA V prop model
   }

2. Test prop models in-game:

   • Create spawn prop command example:/spawnprop prop_beachflag_01

   • Verify model exists in game files

3. Common issues:

   • Typo in prop name

   • DLC prop requiring specific game build

   • Custom prop not installed on server

   • Model streaming issues (add to fxmanifest.lua if needed)

Enable Debug Mode

Problem: Unable to identify what's failing.

Solution:

1. Enable debug mode in configs/sh.config.lua:

   Config.Debug = true
   Config.DevMode = true  -- Additional developer information

2. Check logs in:

   • F8 console (client-side)

   • Server console (server-side)

   • Browser console (NUI errors)

3. Look for specific error messages:

   • Script errors (Lua syntax)

   • Network errors (API calls failing)

   • Asset loading errors (props, images, sounds)

Verify Asset References

Problem: Images, sounds, or UI elements don't load.

Solution:

1. Check image URLs in configs:

   Config.LaptopApp = {
       img = "https://cfx-nui-devhub_laptop/html/images/apps/racing.png",
       -- URL must be accessible
   }

2. Verify sound files exist:

   • Check public/sounds/ folder

   • Files: countdown.wav, fireworks.mp3, swoosh.wav

   • Ensure proper file formats (WAV, MP3, OGG)

3. Check NUI resource path:

   path = "https://cfx-nui-devhub_racing/html/index.html",
   -- Must match resource name exactly

4. Test asset loading:

   • Open browser console (NUI devtools)

   • Check for 404 errors or loading failures

Restart in Correct Order

Problem: Script partially works or has intermittent issues.

Solution:

1. Proper startup order:

   -- server.cfg (correct order)
   ensure devhub_lib
   ensure devhub_skillTree  # if skill tree enabled
   ensure devhub_laptop
   ensure devhub_racing

2. Server restart sequence:

   ensure devhub_lib
   ensure devhub_skillTree
   ensure devhub_laptop
   ensure devhub_racing

3. Individual resource restart:

   refresh  # Refresh resource cache
   ensure devhub_racing  # Start resource

4. Full server restart recommended after:

   • Database changes

   • Major configuration changes

   • Adding/removing dependencies

---

Race Mechanics Issues

Checkpoint Not Detecting

Problem: Players drive through checkpoints but they don't register.

Solution:

1. Check checkpoint marker settings and devMode:

   Config.EnableCheckpointMarkers = true  -- Must be enabled
   Config.DevMode = true

2. Verify checkpoint placement in map:

   • Checkpoints too far apart

   • Checkpoint trigger zone too small

   • Checkpoints placed incorrectly (underground, in air)

3. Test with debug mode enabled:

   • See checkpoint coordinates

   • Verify player position vs checkpoint position

   • Check trigger distance calculations

4. Recreate problematic checkpoints:

   • Edit map in map creator

   • Delete and re-place checkpoint

Race Will Not Start

Problem: Countdown doesn't begin or race is stuck.

Solution:

1. Check minimum player requirement:

   • At least 1 player required

   • Verify players are in waiting room state

2. Verify start time configuration:

   Config.OfficialRaceGenerator = {
       ['Monday'] = {
           {
               start = {hour = 18, minute = 0},  -- Must be valid time
               -- ...
           }
       }
   }

3. Check server time vs configured time:

   • Server might be in different timezone

   • Use /time command to check current server time

   • Adjust scheduled times accordingly

4. Manual race start issues:

   • Check if start delay expired

   • Verify race is not already in progress

   • Ensure no conflicting race instances

Blips Not Showing

Problem: Map markers and checkpoint blips invisible.

Solution:

1. Check blip configuration in configs/sh.config.lua:

   Config.RaceBlips = {
       enabled = true,  -- Must be true
       showDistance = 2000.0,  -- Increase if needed
       -- ...
   }
   
   Config.CheckpointBlips = {
       enabled = true,  -- Must be true
       -- ...
   }

2. Verify player distance to race start:

   • Must be within showDistance range

   • Increase range for testing:

     showDistance = 10000.0,  -- 10km

3. Check for blip sprite conflicts:

   • Try different blip sprite IDs

   • Use unique blip sprites not used elsewhere

Collisions Not Working as Expected

Problem: Player collisions disabled when they should be enabled (or vice versa).

Solution:

1. Check race configuration:

   collisions = true,  -- Player collisions enabled
   collisions = false,  -- Player collisions disabled (ghost mode)

2. Note: Props are always collision-free by design:

   • Prevents players getting stuck on decorations

   • Allows passing through checkpoint markers

   • Cannot be changed via config

3. Verify entity collision settings:

   • Check if other scripts override collision

   • Test in isolated environment (no other scripts)

---

UI and Display Issues

Racing App Not Opening

Problem: Laptop app doesn't display racing interface.

Solution:

1. Check laptop integration:

   Config.LaptopApp = {
       path = "https://cfx-nui-devhub_racing/html/index.html",
       -- Must match resource name
   }

2. Test NUI directly:

   • F8 console: loadnui https://cfx-nui-devhub_racing/html/index.html

   • Check NUI console for errors

3. Ensure laptop resource is compatible:

   • Verify devhub_laptop is installed (if required)

   • Check laptop app registration

Translations Not Displaying

Problem: UI shows translation keys instead of text.

Solution:

1. Check language file completeness in configs/sh.lang.lua:

   Config.Lang = {
       ['already_in_race'] = "You are already in a race!",
       -- All keys must have values
   }

2. Verify translation key matches code:

   • Check for typos in translation keys

   • Ensure key exists in config

   • Use exact key name (case-sensitive)

3. Missing translations:

   • Copy missing keys from default sh.lang.lua

   • Translate to your language

   • Restart resource

Music Not Playing

Problem: Race music doesn't play or is silent.

Solution:

1. Check music configuration in configs/sh.config.lua:

   Config.RaceMusic = {
       enabled = true,  -- Must be true
       volume = 0.2,  -- Increase if too quiet
       tracks = {
           "https://www.youtube.com/watch?v=...",
           -- Must be valid, embeddable YouTube links
       }
   }

2. YouTube embed restrictions:

   • Some videos are blocked by copyright

   • Use royalty-free music or licensed tracks

   • System auto-skips blocked videos to next track

3. Player settings:

   • Press G in-game to toggle music

   • Check game audio settings (not muted)

   • Test with different browsers (NUI)

---

Discord Integration Issues

Webhooks Not Sending

Problem: Discord messages not appearing.

Solution:

1. Verify webhook URLs in configs/s.logs.lua:

   Config.LogsWebhook = "https://discord.com/api/webhooks/1234567890/ABCDEF..."
   Config.OfficialRacesAnnouncementsWebhook = "https://discord.com/api/webhooks/..."

2. Test webhook URLs:

   • Paste in browser (should show "Invalid webhook token" - this is correct)

   • Copy from Discord server settings > Integrations > Webhooks

   • Ensure webhook is not deleted in Discord

3. Check Discord channel permissions:

   • Webhook must have permission to send messages

   • Channel must exist and be accessible

   • Webhook not rate-limited

Announcement Formatting Issues

Problem: Discord messages display incorrectly.

Solution:

1. Check translation strings for webhook in configs/sh.lang.lua:

   Config.Lang = {
       ['webhook_title'] = "🏁 New Official Race Scheduled 🏁",
       ['webhook_description'] = "A new official race has been generated!",
       -- ... all webhook_ keys must exist
   }

2. Verify embed structure in code:

   • Discord embeds have field limits (256 chars for field names, 1024 for values)

   • Check for special characters breaking JSON

   • Validate embed colors (must be valid hex or decimal)

---

Database Issues

Data Not Saving

Problem: Player stats, maps, or races not persisting.

Solution:

1. Verify SQL tables exist:

   SHOW TABLES LIKE 'devhub_racing%';

2. Import SQL file if missing:

   • Locate sql.sql in resource folder

   • Restart server after import

3. Check database permissions:

   • User must have INSERT, UPDATE, DELETE permissions

   • Verify connection in devhub_lib (NEEDED FOR EACH SCRIPT!) config

   • Test with simple query

4. Look for SQL errors in console:

   • Check server console for MySQL errors

   • Common: Duplicate keys, constraint violations

   • Fix data inconsistencies in database

Leaderboard Not Updating

Problem: Leaderboard shows old data or doesn't refresh.

Solution:

1. Check cache timeout:

   Config.LeaderboardCacheTimeout = 60000 * 15  -- 15 minutes

2. Force cache refresh:

   • Wait for cache timeout to expire

   • Restart resource: restart devhub_racing

3. Verify leaderboard query:

   • Check for database errors in console

   • Test query directly in database

   • Ensure proper indexing on database tables

---

General Troubleshooting Checklist

Before reporting issues, verify:

• All dependencies are installed and started (devhub_lib, devhub_laptop)

• Database tables are created from sql.sql

• Config files have no syntax errors

• Server and resource are fully restarted

• Debug mode is enabled to see error messages

• Console (F8 and server) checked for errors

• Your framework is working correctly and is configured in devhub_lib (NEEDED FOR EACH SCRIPT!)

• No conflicting resources are running

• Game cache is cleared (if using custom assets)

• Server artifacts are up to date

If issues persist:

1. Enable debug mode for detailed logs

2. Check client (F8) , server and NUI console

3. Test with minimal configuration (disable features one by one)

4. Verify issue on clean server with only required resources

5. Check for updates to devhub_racing , devhub_lib, devhub_laptop

6. Contact DevHub support with:

   • Server console logs

   • Client console logs (F8)

   • NUI console logs (F8 NUI devtools)

   • Config files (with sensitive data removed [webhooks])

   • Steps to reproduce the issue