Troubleshooting

Troubleshooting & Common Errors

Purpose of This Guide

This troubleshooting guide is designed to help server administrators and users quickly identify and resolve common issues with the GOD - Nail Trap System.

Why is this important?

• Saves Time: Instead of searching through code or asking for help, users can find solutions to common problems immediately

• Reduces Support Load: Most common issues are documented here, reducing repetitive support requests

• Self-Service: Users can fix problems themselves without waiting for support

• Best Practices: Includes prevention tips to avoid issues before they occur

What's included:

• Common error messages and their solutions

• Step-by-step debugging processes

• Prevention tips to avoid future issues

• Configuration verification steps

• Resource dependency checks

This guide helps you diagnose and fix common issues with the GOD - Nail Trap System.

Common Errors

Error: "ox_lib not found" or "ox_lib export not available"

Symptoms:

• Script fails to start

• Progress bars don't work

• Notifications don't appear (ESX)

Solution:

1. Ensure ox_lib is installed and up to date

2. Verify ox_lib is started before J0-nailScript in server.cfg:

   ensure ox_lib
   ensure J0-nailScript

3. Restart both resources

Prevention:

• Always start dependencies before dependent resources

• Keep ox_lib updated to the latest version

---

Error: "Framework export not found" or "Core object not available"

Symptoms:

• Script fails to initialize

• Items don't work

• Server console shows framework errors

Solution:

1. Verify your framework is running:

   • QBCore: Check qb-core is started

   • ESX: Check es_extended is started

   • Qbox: Check qbox_core is started

2. Check shared/config.lua matches your framework:

   J0.Core = "QBCore" -- Must match your framework

3. Ensure framework resource is started before J0-nailScript

Prevention:

• Double-check framework name spelling

• Verify framework resource name matches exports

---

Error: "Inventory export/function not found"

Symptoms:

• Items can't be added/removed

• Server errors when using nails

• Inventory operations fail

Solution:

1. Verify inventory system is running:

   • ox_inventory: Check resource is started

   • qb-inventory: Check resource is started

2. Check shared/config.lua matches your inventory:

   J0.Inventory = 'ox' -- or 'qb'

3. For ESX, ensure you've registered useable items (see Installation Guide)

Prevention:

• Match inventory configuration to installed system

• Test inventory functions separately

---

Error: "Targeting system not found" or "Target export not available"

Symptoms:

• Can't interact with nails

• "Remove Nails" option doesn't appear

• Targeting errors in console

Solution:

1. Verify targeting system is installed and running:

   • ox_target: Check resource is started

   • qb-target: Check resource is started

   • interact: Check resource is started

2. Check shared/config.lua matches your targeting system:

   J0.Target = "ox_target" -- Must match installed system

3. Ensure targeting resource is started before J0-nailScript

4. As a fallback, try setting to "interact" if you have it installed

Prevention:

• Install a compatible targeting system

• Verify targeting system exports are available

---

Error: "Failed to create nail object" or "Entity does not exist"

Symptoms:

• Nails don't appear when placed

• Items are consumed but nothing spawns

• Client console shows object creation errors

Solution:

1. Verify custom prop model is available:

   • Check if prop is streamed in your server

   • Verify custom model is installed correctly

   • Ensure model files are in the correct location

2. Check client console for specific error messages

3. Verify player has proper permissions to spawn objects

4. Contact support if you need to use a different prop model

Prevention:

• Ensure custom props are properly streamed

• Test prop spawning separately

---

Error: Items consumed but nails don't spawn

Symptoms:

• Item disappears from inventory

• No nail appears in game

• No error messages

Solution:

1. Check server console for errors during nail placement

2. Verify custom prop model exists and is streamed

3. Check client console for spawn errors

4. Verify ox_lib progress bar completes successfully

5. Check if player has proper coordinates (not in invalid location)

Prevention:

• Test in a known-good location

• Verify all dependencies are working

---

Error: Nails don't damage tires

Symptoms:

• Nails are visible and vehicles drive over them

• No tire damage occurs

• Tires don't burst

Solution:

1. Verify damage configuration in shared/config.lua:

   J0.NailsCfg = {
       DamagePerNail = 33.335 -- Ensure this is set
   }

2. Check if vehicle has proper wheel bones (most vehicles do)

3. Verify you're actually driving over the nail (within 0.5 units)

4. Check client console for damage detection errors

5. Test with a different vehicle

Prevention:

• Test damage settings in configuration

• Verify vehicle models have proper bone structure

---

Error: "You Can't Place More Than 20 At A Time"

Symptoms:

• Message appears when using nail package

• Can't place more nails

Solution: This is not an error - it's the built-in limit. To change it:

1. Contact support for assistance with adjusting the maximum nails per package limit

Prevention:

• Adjust limit based on server needs

• Inform players of the limit

---

Error: Nails disappear immediately or too quickly

Symptoms:

• Nails vanish right after placement

• Cleanup happens too fast

Solution:

1. Check J0.NailsCfg.CleanUp value in shared/config.lua:

   J0.NailsCfg = {
       CleanUp = 10, -- Value in minutes, increase if too short
   }

2. Verify value is in minutes, not seconds

3. Check if there are multiple cleanup timers running (shouldn't happen)

Prevention:

• Set appropriate cleanup time for your server

• Test cleanup timing

---

Error: Script causes server lag or high resmon

Symptoms:

• Server performance degrades

• High resource monitor usage

• FPS drops

Solution:

1. Check for too many active nails (hundreds can cause issues)

2. Verify cleanup timer is working (nails should disappear after set time)

3. Check for script conflicts with other resources

4. Ensure ox_lib is up to date

5. Contact support for assistance with optimizing damage detection range if needed

Prevention:

• Keep cleanup time reasonable (5-15 minutes)

• Monitor active nail count

• Update dependencies regularly

---

Debugging Steps

General Debugging Process

1. Check Console Logs

   • Server console for server-side errors

   • Client console (F8) for client-side errors

   • Look for Lua errors, missing exports, or nil values

2. Verify Dependencies

   • Ensure all required resources are started

   • Check resource start order in server.cfg

   • Verify resource versions are compatible

3. Test Configuration

   • Verify shared/config.lua settings are correct

   • Check for typos in framework/inventory/target names

   • Ensure all values are valid (numbers where needed)

4. Isolate the Issue

   • Test with minimal configuration

   • Disable other scripts to check for conflicts

   • Test in a clean environment

5. Check Resource Status

   • Use ensure command to verify resources are loaded

   • Check resource status in server console

   • Verify no resource conflicts

Console Commands for Debugging

Check if resource is running:

ensure J0-nailScript

Restart resource:

restart J0-nailScript

Check resource status:

status

Common Debug Scenarios

Scenario 1: Script Won't Start

1. Check server.cfg for resource entry

2. Verify ox_lib is started first

3. Check console for specific error

4. Verify file structure is correct

5. Check fxmanifest.lua for syntax errors

Scenario 2: Items Don't Work

1. Verify items are added to inventory correctly

2. Check item names match exactly

3. Verify useable item registration (ESX)

4. Check inventory system is running

5. Test item usage in inventory

Scenario 3: Nails Don't Spawn

1. Check custom prop availability

2. Verify client console for errors

3. Check if progress bar completes

4. Verify player coordinates are valid

5. Test with different location

Scenario 4: Targeting Doesn't Work

1. Verify targeting system is installed

2. Check configuration matches installed system

3. Test targeting system separately

4. Verify targeting resource is started

5. Try different targeting system as test

Prevention Tips

1. Always Start Dependencies First

   • ox_lib before J0-nailScript

   • Framework before J0-nailScript

   • Targeting system before J0-nailScript

2. Verify Configuration

   • Double-check framework name spelling

   • Match inventory system correctly

   • Verify targeting system name

3. Test After Changes

   • Test in development environment first

   • Verify all features work after configuration changes

   • Check console for errors

4. Keep Resources Updated

   • Update ox_lib regularly

   • Keep framework updated

   • Update targeting system if needed

5. Monitor Performance

   • Check resmon usage

   • Monitor active nail count

   • Watch for memory leaks

Getting Help

If you've tried all troubleshooting steps and still have issues:

1. Gather Information:

   • Server console errors

   • Client console errors (F8)

   • Configuration file contents

   • Resource versions (ox_lib, framework, etc.)

2. Check Documentation:

   • Review Installation Guide

   • Check Configuration Guide

   • Read FAQ

3. Contact Support:

   • Provide error messages

   • Include configuration details

   • Describe steps to reproduce issue

---

Most issues can be resolved by verifying dependencies, configuration, and resource start order.