# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tworst.com/guides/troubleshooting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.