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

# FAQ & Troubleshooting

<details>

<summary><strong>The NPC doesn't spawn</strong></summary>

* Ensure `Config.UI.ShowPeds = true`
* Check that the ped model name is valid (e.g., `"s_m_y_dealer_01"`)
* Verify spawn coordinates are correct (not underground)
* Check console for `[FB-Blackmarket]` error messages

</details>

<details>

<summary><strong>Items show placeholder images</strong></summary>

* Set `Config.UseInventoryImages = true`
* Verify `Config.InventoryImagePath` points to your inventory's image folder
* Example: `"nui://qb-inventory/html/images/"`

</details>

<details>

<summary><strong>Framework not detected</strong></summary>

* Set `Config.Framework` manually: `"qbcore"`, `"esx"`, etc.
* Ensure your framework resource is started before fb-blackmarket

</details>

<details>

<summary><strong>Purchases fail silently</strong></summary>

* Enable `Config.Debug = true` and check server console
* Verify the item exists in your framework's item registry
* Check that the player has sufficient funds

</details>

<details>

<summary><strong>Database errors</strong></summary>

* Ensure you've imported `blackmarket.sql`
* Check your database connection in server.cfg
* Verify MySQL/MariaDB is using `utf8mb4` charset

</details>

<details>

<summary><strong>Admin panel doesn't open</strong></summary>

* The panel requires a server event trigger with proper permissions
* Check that `settings.html` is included in the `files {}` manifest

</details>

<details>

<summary><strong>Voice cues not playing</strong></summary>

* Verify sound files exist in `sounds/` subdirectories
* Check `Config.VoiceCues.Enabled = true`
* Ensure Volume is > 0

</details>