> For the complete documentation index, see [llms.txt](https://sl-scritps.gitbook.io/sl-scripts-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sl-scritps.gitbook.io/sl-scripts-documentation/troubleshooting.md).

# Troubleshooting

## Troubleshooting

This page lists common issues that may happen when installing or using SL Scripts resources.

Before asking for support, please check the points below.

***

### First checks

If something is not working, start here:

```txt
1. Is the resource folder name correct?
2. Is the resource added to server.cfg?
3. Are dependencies started before the resource?
4. Did you configure config.lua?
5. Did you configure custom.lua if needed?
6. Did you import SQL if required?
7. Are there server console errors?
8. Are there client F8 errors?
9. Are permissions configured correctly?
10. Are you using the correct item, command or target interaction?
```

***

### Resource does not start

Check the server console after starting the resource.

Common causes:

```txt
- Wrong folder name
- Missing fxmanifest.lua
- Missing dependency
- Missing file referenced in fxmanifest.lua
- Syntax error in config.lua
- SQL dependency not started
- Resource ensured before required dependencies
```

Recommended checks:

```txt
ensure oxmysql
ensure ox_lib
ensure ox_inventory
ensure ox_target

ensure sl_resource_name
```

Make sure the resource folder is not renamed incorrectly.

***

### Missing file warnings

If the console shows warnings about missing files, it usually means the `fxmanifest.lua` references files that are not inside the resource folder.

Example:

```txt
Could not find file docs/README.md
Could not find file CHANGELOG.md
```

Fix:

```txt
1. Check fxmanifest.lua.
2. Remove references to files that are not included.
3. Make sure all listed client/server/shared/web files exist.
4. Restart the resource.
```

***

### NUI does not open

If the UI does not open, check:

```txt
- The resource has a web/ folder.
- ui_page is correctly declared in fxmanifest.lua.
- Files listed under files { } exist.
- F8 console does not show JavaScript errors.
- The command, item or target interaction is working.
- NUI callbacks are registered correctly.
```

Also check if another UI is blocking focus.

Try:

```txt
restart sl_resource_name
```

Then reconnect to the server and test again.

***

### Black box or dark rectangle behind UI

If you see a black rectangle behind a NUI element, it is usually a CSS transparency issue.

Common causes:

```txt
- body has a black background
- root wrapper has a black background
- fullscreen overlay has a solid background
- opacity is used on the whole UI container
- backdrop-filter creates rendering artifacts
```

Recommended pattern:

```css
html,
body,
#app,
#root {
    background: transparent !important;
}
```

Use transparent backgrounds only on the actual UI card or panel, not on the fullscreen wrapper.

***

### SQL errors

If the resource uses database tables, check:

```txt
- oxmysql is installed.
- oxmysql starts before the resource.
- Database connection is working.
- sql/install.sql was imported if required.
- The database user has permission to create/alter tables.
- Table names were not changed incorrectly.
```

Recommended order:

```cfg
ensure oxmysql
ensure sl_resource_name
```

If automatic migrations are enabled, check the server console for migration messages.

***

### Target interaction does not appear

Check:

```txt
- ox_target or qb-target is installed.
- The target resource starts before the SL Scripts resource.
- Target mode is enabled in config.lua.
- You are close enough to the object, NPC or zone.
- Your job or permission allows access.
- The configured model exists.
- The interaction was registered after the entity spawned.
```

Try moving away and coming back, or restarting the resource.

***

### Item does not work

If a usable item does not activate the resource, check:

```txt
- The item exists in your inventory system.
- The item name matches config.lua exactly.
- The inventory bridge is configured correctly.
- The item was added to your inventory database/config.
- The resource supports your inventory system.
- Server console does not show item registration errors.
```

Example:

```lua
Config.ItemName = 'smartwatch'
```

The inventory item must also be named:

```txt
smartwatch
```

***

### Command does not work

Check:

```txt
- Commands are enabled in config.lua.
- You are using the correct command.
- You have permission to use the command.
- The resource is started.
- F8 console does not show errors.
```

Example:

```txt
/smartwatch
/scene
/rolmaker
```

Some commands are admin-only.

***

### Permissions do not work

Permissions may depend on the product.

Check:

```txt
- Ace permissions
- Framework group
- Job name
- Job grade
- Config admin list
- custom.lua permission bridge
```

Common permission levels:

```txt
view
use
manage
admin
owner
```

If you are testing as owner/admin, make sure your group is correctly detected by your framework or permission system.

***

### Admin panel does not show

Check:

```txt
- You have admin/owner permission.
- Admin features are enabled in config.lua.
- Your framework group is detected correctly.
- The admin command or button is enabled.
- custom.lua permission bridge is not blocking access.
```

If the product has debug mode, enable it temporarily and check the console.

***

### Webhook does not send

Check:

```txt
- Webhook URL is valid.
- Webhooks are enabled in config.lua.
- The server can reach Discord.
- The webhook was not deleted.
- The event you are testing actually triggers a log.
```

Never share webhook URLs publicly.

***

### Asset Escrow / entitlement errors

If the resource shows Asset Escrow errors, check:

```txt
- The asset was purchased or granted to the correct CFX account.
- The server license key belongs to the correct CFX account.
- The resource was downloaded from CFX/Tebex delivery.
- The resource folder was not modified incorrectly.
- You are not trying to run protected files from an unofficial copy.
```

If the issue continues, verify the asset in your CFX account.

***

### Resource works after restart but not after full server reboot

Check ensure order.

Dependencies must start before the SL Scripts resource.

Example:

```cfg
ensure oxmysql
ensure ox_lib
ensure ox_inventory
ensure ox_target

ensure sl_resource_name
```

If the resource depends on a framework, make sure the framework starts first.

***

### No startup log appears

If startup logs are enabled but do not appear:

```txt
- Check Config.StartupLogs.
- Check Config.Debug.
- Check server console.
- Check client F8 console.
- Confirm the resource actually started.
```

Some resources may only show startup logs on server, client or both depending on the product.

***

### Version mismatch

When asking for support, always check the installed version.

The version may appear in:

```txt
- Startup logs
- NUI footer
- Admin panel
- About section
- README.md
- Product page
```

Example:

```txt
SL Smartwatch GPS · v1.8.14
```

Always report the exact version.

***

### What to send when asking for support

When contacting support, include:

```txt
1. Product name
2. Resource name
3. Version
4. Framework
5. Inventory system
6. Target system
7. Server console error
8. Client F8 error
9. What you were doing when the issue happened
10. Screenshots or video if possible
```

This helps identify the issue faster.

***

### Still need help?

Check the product-specific page first.

If the issue continues, contact support through the official Discord.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://sl-scritps.gitbook.io/sl-scripts-documentation/troubleshooting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.