Common Issues

Solutions to frequently encountered problems.

Installation Issues

Script fails to start

Symptoms:

• Resource doesn't appear as started

• No console output

Solutions:

1

Check load order in server.cfg

# Correct order
ensure ox_lib
ensure oxmysql
ensure qb-core  # Your framework
ensure hsJobQuestV2

2

Verify file structure

resources/[jobs]/hsJobQuestV2/
├── client/
├── server/
├── shared/
├── data/
└── fxmanifest.lua

3

Check for syntax errors

# Look for Lua errors in console
[script:hsJobQuestV2] SCRIPT ERROR: ...

Database errors on startup

Symptoms:

[ERROR] MySQL error: Table 'hsjobquest_players' doesn't exist

Solutions:

1

Import the SQL file

• Open your database manager

• Select your FiveM database

• Import install.sql

2

Check database credentials

# In server.cfg
set mysql_connection_string "mysql://user:password@localhost/database"

3

Verify table creation

SHOW TABLES LIKE 'hsjobquest%';

Gameplay Issues

NPC doesn't appear

Symptoms:

• Job hub location is empty

• Can't find the postal worker

Solutions:

1

Check coordinates

Config.JobStartLocation = vec4(154.17, -3075.09, 5.9, 86.59)

2

Verify ped model

Config.JobPedModel = 's_m_m_postal_01'
-- Try a different model if this fails

3

Check for OneSync issues

• NPCs may not spawn if entity limit reached

• Restart the resource

Can't interact with NPC

Symptoms:

• NPC visible but no interaction prompt

Solutions:

1

Check target system

Config.TargetSystem = 'qb-target'  -- Match your server

2

Verify target resource running

ensure qb-target  # or ox_target

3

Check for target zone conflicts

• Other scripts may override zones

Mission won't start

Symptoms:

• "Failed to generate mission" error

• Nothing happens when selecting job

Solutions:

1

Check rank requirement

-- Job requires rank, player doesn't meet it
Config.Jobs.luxury_goods_delivery.requiredRank = 3

2

Already have active mission

• Cancel current mission first

3

Check server console for errors

• Enable debug mode

• Look for mission generation errors

Vehicle doesn't spawn

Symptoms:

• Mission starts but no vehicle

Solutions:

1

Check vehicle model

Config.Jobs.food_delivery.vehicle = 'brioso'
-- Ensure model exists in game

2

Spawn point blocked

• Another vehicle at spawn location

• Invalid spawn coordinates

3

Vehicle hash not loading

-- Check client console
[script:hsJobQuestV2] Vehicle model 'xyz' not found

Data Issues

XP/Rank not saving

Symptoms:

• Progress resets on rejoin

• Database shows old values

Solutions:

1

Check database connection

• Verify oxmysql is running

• Check connection string

2

Enable debug mode

Config.EnableDebug = true
-- Look for database errors

3

Check player identifier

-- Should match framework's identifier
[hsJobQuest] Player initialized: ABC123

Achievements not unlocking

Symptoms:

• Requirements met but not unlocked

• Progress shows but won't complete

Solutions:

1

Verify achievements enabled

Config.EnableAchievements = true

2

Check achievement table

SELECT * FROM hsjobquest_achievements WHERE citizenid = 'ABC123';

3

Manual trigger for testing

• Complete a delivery and check debug output

ATM balance shows 0

Symptoms:

• Completed missions but $0 balance

• Withdrawals fail

Solutions:

1

Check payout type

Config.PayoutType = 'cash'  -- Goes to ATM
-- vs 'bank' which goes directly

2

Verify database money column

SELECT money FROM hsjobquest_players WHERE citizenid = 'ABC123';

3

Check for transaction errors

• Enable debug mode

• Look for AddMoney failures

Performance Issues

High CPU usage

Symptoms:

• Server lag when script running

• Tick rate drops

Solutions:

1

Disable debug mode

Config.EnableDebug = false

2

Check for infinite loops

• Review any custom code added

3

Database optimization

• Add indexes if missing

• Clear old transaction history

Memory leaks

Symptoms:

• Memory usage grows over time

• Script slows down

Solutions:

1

Restart the resource periodically

restart hsJobQuestV2

2

Check for uncached data

• Database queries should be cached

Integration Issues

Phone notifications not working

Symptoms:

• No phone messages during illegal runs

• Notification errors

Solutions:

1

Check phone system detection

Config.PhoneSystem = 'auto'  -- Or specify: 'yseries', 'qs-smartphone'

2

Verify phone resource running

ensure yseries  # Your phone

3

Check export compatibility

• Some phones require specific formats

Fuel system not working

Symptoms:

• Fuel Master skill has no effect

• Fuel saver not saving

Solutions:

1

Check fuel system detection

Config.FuelSystem = 'auto'

2

Verify fuel resource name

-- Must match exactly
Config.FuelSystem = 'LegacyFuel'  -- Case sensitive

3

Use custom fuel system

Config.FuelSystem = 'custom'
Config.CustomFuelSystem = {
    GetFuel = function(vehicle) ... end,
    SetFuel = function(vehicle, amount) ... end
}

Getting More Help

If your issue isn't listed:

1

Enable Debug Mode

Config.EnableDebug = true

2

Collect Information

• Console errors

• Steps to reproduce

• Server/framework versions

3

Contact Support

• Discord: HyperScripts

• Include all collected info