⚠️ Troubleshooting

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:

   LuaCopy

   -- server.cfg
   ensure devhub_lib
   ensure devhub_laptop
   ensure devhub_racing

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

   LuaCopy

   -- 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:

   ShellCopy

   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:

   LuaCopy

   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:

   LuaCopy

   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:

   LuaCopy

   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:

   SQLCopy

   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:

   LuaCopy

   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:

   LuaCopy

   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:

   LuaCopy

   -- 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:

   LuaCopy

   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:

   LuaCopy

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

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

   LuaCopy

   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:

   LuaCopy

   -- 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:

   LuaCopy

   -- 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:

   LuaCopy

   {
       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:

   LuaCopy

   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:

   LuaCopy

   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:

   LuaCopy

   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:

   LuaCopy

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

2. Server restart sequence:

   LuaCopy

   ensure devhub_lib
   ensure devhub_skillTree
   ensure devhub_laptop
   ensure devhub_racing

3. Individual resource restart:

   LuaCopy

   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:

   LuaCopy

   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:

   LuaCopy

   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:

   LuaCopy

   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:

     LuaCopy

     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:

   LuaCopy

   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:

   LuaCopy

   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:

   LuaCopy

   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:

   LuaCopy

   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:

   LuaCopy

   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:

   LuaCopy

   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:

   SQLCopy

   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:

   LuaCopy

   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