> For the complete documentation index, see [llms.txt](https://docs.tworst.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tworst.com/getting-started-installation/guides/troubleshooting.md).

# Troubleshooting

Common issues and solutions for Tworst Scripts.

***

## Script Won't Start

### Check Resource Name

Resource names are **case-sensitive** on Linux servers:

```cfg
# Correct
ensure tw-scrapyard

# Wrong (case sensitive on Linux)
ensure TW-Scrapyard
ensure Tw-scrapyard
```

### Check Load Order

Make sure dependencies start **before** Tworst Scripts:

```cfg
# server.cfg - Correct order
ensure oxmysql          # Database (must be first)
ensure es_extended      # or qb-core (framework)
ensure PolyZone         # Required for all Tworst Scripts
ensure tw-scriptname    # Tworst Scripts last
```

{% hint style="warning" %}
**PolyZone** is required for all Tworst Scripts. Make sure it's installed and started before the script.
{% endhint %}

### Check Resource Folder

1. Verify the resource is in the correct `resources` folder
2. Check that the folder name matches exactly (no spaces or special characters)
3. Make sure all files were extracted properly

### Check Console for Errors

* Press **F8** in-game to see client console
* Check server console for red error messages
* Look for specific error messages to identify the issue

***

## Framework Issues

### "ESX not found" or "QBCore not found"

Your framework setting doesn't match your server:

```lua
-- config/config.lua

-- For QBCore servers:
Config.Framework = 'qb'

-- For older QBCore versions:
Config.Framework = 'oldqb'

-- For QBox servers (uses 'qb'):
Config.Framework = 'qb'

-- For ESX Legacy servers:
Config.Framework = 'esx'

-- For older ESX versions:
Config.Framework = 'oldesx'

-- For vRP servers:
Config.Framework = 'vrp'

-- For vRP2 servers:
Config.Framework = 'vrp2'

-- For standalone (no framework):
Config.Framework = 'standalone'
```

### "attempt to index a nil value (global 'ESX')"

1. Check if your framework is starting properly
2. Verify the framework resource name in your `server.cfg`
3. Make sure `Config.Framework` matches your actual framework

### "No such export" Error

Missing dependency. Check that you have:

* **PolyZone** - Required for all scripts
* **oxmysql** (or mysql-async/ghmattimysql) - Database resource
* Your framework (ESX/QBCore/vRP)

***

## UI Not Showing

### Step 1: Clear FiveM Cache

Delete the FiveM cache folder:

```
%localappdata%/FiveM/FiveM.app/data/cache
```

Or in FiveM settings, click **"Clear Cache"**.

### Step 2: Check NUI Files

Verify the `html/` folder exists in the resource and contains all files.

### Step 3: Check Browser Console

1. Press **F8** in-game
2. Go to the **NUI** tab
3. Look for JavaScript errors (red text)

### Step 4: Check for Conflicts

Another script might be blocking NUI. Try disabling other UI scripts temporarily.

***

## Database Issues

### Tables Not Creating Automatically

{% hint style="info" %}
Tworst Scripts automatically create database tables on first start. If this fails:
{% endhint %}

1. Check your database resource is running (`oxmysql`, `mysql-async`, or `ghmattimysql`)
2. Verify `Config.SQL` matches your database resource
3. Check database connection in `server.cfg`
4. Manually import `insert.sql` as a last resort

### "Table doesn't exist"

If automatic creation failed:

1. Find the `insert.sql` file in the script folder
2. Import it using HeidiSQL, phpMyAdmin, or command line
3. Restart the server

### "Connection refused" / "Access denied"

Check your database connection string in `server.cfg`:

```cfg
set mysql_connection_string "mysql://user:password@localhost/database_name?charset=utf8mb4"
```

Make sure:

* Username and password are correct
* Database exists
* User has proper permissions

***

## In-Game Issues

### Job Menu Doesn't Open

1. Check if you're at the correct location (see `config/coordinate.lua`)
2. Verify your interaction system is configured correctly:

   ```lua
   Config.InteractionHandler = 'drawtext'  -- or 'ox-target', 'qb-target'
   ```
3. Enable debug mode to see console messages:

   ```lua
   Config.Debug = true
   ```
4. Check if blips/markers are showing on the map

### Markers/Blips Don't Show

1. Check coordinates in `config/coordinate.lua`
2. Verify blip settings are enabled in config
3. Check for coordinate conflicts with other scripts

### Vehicles Don't Spawn

1. Check vehicle model names are correct in config
2. Verify vehicle key system is configured:

   ```lua
   Config.Vehiclekey = true
   ```
3. The script auto-detects your vehicle key system

### Items Not Given / Inventory Issues

1. Check `Config.Inventory` matches your inventory system:

   ```lua
   Config.Inventory = "qb_inventory"  -- or 'ox_inventory', 'esx_inventory', etc.
   ```
2. Make sure items exist in your inventory system
3. Check `Config.InventoryImagePath` for correct image paths

***

## Config Syntax Errors

### "attempt to call a nil value" in config

You have a syntax error. Check for:

* Missing commas between values
* Unclosed brackets `{}` or parentheses `()`
* Mismatched quotes `"` or `'`

```lua
-- Wrong (missing comma)
Config.Setting = 'value'
Config.Other = true

-- Correct
Config.Setting = 'value',
Config.Other = true,
```

### Changes to Config Don't Apply

1. **Save the file** (Ctrl+S)
2. **Restart the resource**: `ensure tw-scriptname`
3. Or restart the entire server
4. Check for syntax errors preventing load

***

## Performance Issues

### High Resource Usage (resmon)

1. **Disable debug mode** in production:

   ```lua
   Config.Debug = false
   Config.DebugCommands = false
   ```
2. Check for conflicts with other resources
3. Reduce draw distances if configurable

### Lag Spikes

1. Check database query efficiency
2. Monitor with `resmon` command in F8 console
3. Ensure database resource is optimized

{% hint style="info" %}
Some higher usage is normal during:

* Initial script load
* Many players using the script simultaneously
* Debug mode enabled
  {% endhint %}

***

## Common Error Messages

| Error Message                                    | Cause                  | Solution                                         |
| ------------------------------------------------ | ---------------------- | ------------------------------------------------ |
| `attempt to index a nil value (global 'ESX')`    | Framework not detected | Check `Config.Framework` setting                 |
| `attempt to index a nil value (global 'QBCore')` | Framework not detected | Check `Config.Framework` setting                 |
| `No such export`                                 | Missing dependency     | Install required resource (PolyZone, etc.)       |
| `SCRIPT ERROR: @tw-...`                          | Script error           | Check full error message, report to support      |
| `Table 'tw_...' doesn't exist`                   | Database issue         | Import `insert.sql` or check database connection |

***

## Debug Mode

Enable debug mode to get more information about issues:

```lua
Config.Debug = true
Config.DebugCommands = true  -- Enables debug commands
```

Debug mode will show:

* Console messages for each action
* Coordinate information
* State changes

{% hint style="warning" %}
**Remember:** Always disable debug mode on production servers for better performance.
{% endhint %}

***

## Still Need Help?

{% hint style="info" %}
Can't solve your issue? Join our [Discord server](https://discord.gg/tworst) and open a support ticket with:

* **Script name** and version
* **Framework** (ESX/QBCore/QBox/vRP) and version
* **Full error message** from server console (F8)
* **Steps to reproduce** the issue
* **Config changes** you made
* **Screenshots** if applicable

Our team is available **7 days a week**!
{% endhint %}