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

# Troubleshooting

Fixes for the most common problems.

{% hint style="info" %}
First step, always: look at the **server console** and the player's **F8 console**. Set `Config.Debug = true` and restart the resource for more detail. The startup banner (`[Chapo_advanced_clothing] v1.0.0 started | framework: ...`) shows the detected framework.
{% endhint %}

## Startup

<details>

<summary>"You lack the required entitlement" / the resource won't start</summary>

See [Escrow and common errors](/visionstore-docs/getting-started/escrow-and-common-errors.md). The server key must belong to the account that bought the script.

</details>

<details>

<summary><code>Couldn't find resource Chapo_advanced_clothing</code></summary>

The folder must sit directly in `resources/` or in a `[category]` folder, never inside another resource, and keep its exact name `Chapo_advanced_clothing`.

</details>

<details>

<summary><code>illenium-appearance is not running</code> when opening a menu</summary>

illenium-appearance is missing, not started, still starting, or its folder isn't named exactly `illenium-appearance`. Install it, start it **before** Vision Clothing and check the console for illenium errors. See [illenium-appearance setup](/visionstore-docs/scripts/advanced-clothing/illenium-setup.md).

</details>

<details>

<summary>The banner says <code>framework: standalone</code> but I use QBCore / ESX</summary>

The script started before your framework. Move `ensure Chapo_advanced_clothing` **below** your framework and illenium-appearance in `server.cfg`.

</details>

<details>

<summary><code>Failed to create the Chapo_advanced_clothing_* tables</code></summary>

Your database user can't create or alter tables, oxmysql isn't connected, or `Config.AutoCreateTables = false`. Import `install/chapo_advanced_clothing.sql` manually, or make sure `ensure oxmysql` comes first. If `player_outfits`, `player_outfit_codes` or `playerskins` are missing, import illenium's own SQL files.

</details>

## illenium hand-over

<details>

<summary>Two prompts, two blips or two peds at a store, barber, tattoo parlour or the police locker</summary>

illenium-appearance still has its own shops. Empty `Config.Stores`, `Config.ClothingRooms` and `Config.PlayerOutfitRooms` and switch off its target / ped options: [illenium-appearance setup](/visionstore-docs/scripts/advanced-clothing/illenium-setup.md), step 2.

</details>

<details>

<summary>illenium's own menu or character creator opens instead of Vision Clothing's</summary>

The guard lines in `illenium-appearance/client/client.lua` are missing, usually after an illenium update. Re-apply step 3 of [illenium-appearance setup](/visionstore-docs/scripts/advanced-clothing/illenium-setup.md) and restart. If your multicharacter calls illenium's `startPlayerCustomization` export directly, point it at `OpenCharacterCreator` instead.

</details>

<details>

<summary>After saving the character, the spawn doesn't continue</summary>

Your multicharacter opened Vision Clothing's creator directly instead of going through illenium's `InitializeCharacter()`. Continue your spawn on the `Chapo_advanced_clothing:client:characterCreated` event (see [Integration examples](/visionstore-docs/scripts/advanced-clothing/developers/integration-examples.md)).

</details>

<details>

<summary><code>/pedmenu</code> opens illenium's menu or answers NOT ALLOWED</summary>

Set `Config.EnablePedMenu = false` in illenium's `shared/config.lua`. Vision Clothing registers `/pedmenu` itself as an alias of `/clothingshop`.

</details>

## Opening menus

<details>

<summary><code>/clothingshop</code> or <code>/giveped</code> says I'm not allowed</summary>

Your account needs to be in the ace group from `Config.Commands` (`group.admin`): `add_principal identifier.license:... group.admin`. Or run the command from the server console with a player id.

</details>

<details>

<summary>TOO FAR FROM THE SHOP</summary>

The server allows `radius + Config.ShopDistanceTolerance` around the shop's `coords` (shipped stores: 3 + 15 m), on open and again at checkout. Move `coords` to where players stand, or raise the tolerance.

</details>

<details>

<summary>NOT ALLOWED at a store or locker</summary>

The shop or wardrobe rules (`job`, `gang`, `minGrade`, `gender`, `citizenids`, `onDutyOnly`) don't match the player, the shop was opened in another mode than its own, or an export used an unknown id. Compare the entry in `config/shops.lua` with the player's job, gang, grade and duty.

</details>

<details>

<summary>No prompt at a wardrobe or locker</summary>

Expected for players who don't meet its rules: restricted wardrobes hide their prompt. Shops always show it.

</details>

<details>

<summary>Two prompts: a target option and an [E] text</summary>

Set `Config.Interaction.useTarget` explicitly (`"ox"`, `"qb"` or `"none"`), and start your target resource **before** Vision Clothing.

</details>

<details>

<summary>A section tab says THAT SECTION IS NOT AVAILABLE HERE</summary>

That place doesn't expose the section. A barber shows HAIR only on purpose. Give the entry a different `type` or a `sections` list (see [Shops and locations](/visionstore-docs/scripts/advanced-clothing/configuration/shops-and-locations.md)).

</details>

## Stuck states

<details>

<summary>The cursor stays on screen, the camera is stuck or the player is frozen</summary>

A Lua error interrupted the menu. Run `restart Chapo_advanced_clothing`: it releases the cursor, removes the camera, unfreezes the player and puts their appearance back. Then look for the error in F8. To close a single player's menu: `TriggerClientEvent("Chapo_advanced_clothing:client:forceClose", src, "admin")`.

</details>

<details>

<summary>ESC does nothing: FINISH CREATING YOUR CHARACTER FIRST</summary>

The character creator can't be skipped by design (`Config.CharacterCreator.allowCancel = false`). Press **SAVE CHARACTER**, or set `allowCancel = true`.

</details>

<details>

<summary>The menu closed by itself</summary>

The player died (`Config.PlayerState.closeOnDeath`) or ended up more than 25 m from where the menu opened (`closeOnDistance`). Raise `closeOnDistance` for large interiors, or set it to `0`.

</details>

## Money and checkout

<details>

<summary>INSUFFICIENT FUNDS although the player has money</summary>

The first account in `Config.Payment.order` that covers the **whole** total pays. If your server has no cash account, use `order = { "bank" }`, or let players pick with `allowChoice = true`. Custom banking setups may need `bridge/framework/server.lua` adapted ([Framework bridge](/visionstore-docs/scripts/advanced-clothing/developers/framework-bridge.md)).

</details>

<details>

<summary>The money boxes show $0</summary>

The framework wasn't detected (standalone) or started after Vision Clothing. Fix the start order and check the banner.

</details>

<details>

<summary>SOMETHING WENT WRONG on CONFIRM</summary>

The server checkout failed. Turn on `Config.Debug` and read the server console: usually `bridge/framework/server.lua` doesn't match your framework version.

</details>

<details>

<summary>NOTHING TO BUY / NOTHING CHANGED</summary>

Nothing differs from what the player wore when the menu opened (or only colours changed with `Config.FreeTextureChanges = true`). Expected.

</details>

<details>

<summary>ITEM LOCKED / ITEM NOT AVAILABLE HERE</summary>

A `Config.LockedItems` rule matches, or the item is outside the shop's `categories`, `whitelist` or `blacklist`. Adjust the rule or the shop entry.

</details>

## Clothing and thumbnails

<details>

<summary>Add-on clothing shows placeholders</summary>

Expected: the shipped thumbnails cover base-game and Rockstar DLC clothing only. Add your own: [Add-on thumbnails](/visionstore-docs/scripts/advanced-clothing/guides/addon-thumbnails.md). Decals have no shipped images either.

</details>

<details>

<summary>Every card shows a placeholder</summary>

Check the paths: with the default config, male top 15 must be `html/assets/images/components/male/11/_base/15.webp`. If you added images, re-run `node tools/build-manifest.js`. If it's only a few players, they should update their FiveM client.

</details>

<details>

<summary>Images show on the wrong items</summary>

Your patterns use `{drawable}` (numbered layout) and a clothing pack was added, removed or reordered. Use the shipped pack-layout patterns, or convert your pack (see [Add-on thumbnails](/visionstore-docs/scripts/advanced-clothing/guides/addon-thumbnails.md)).

</details>

<details>

<summary>Selecting a top changes the arms or undershirt</summary>

That's the clipping rules in `config/compatibility.lua`. Edit the rule, or set `Config.CompatibilityMode = "free"`.

</details>

<details>

<summary>The colour filter shows no items</summary>

The colour index hasn't been built yet. Run `/clothingcolors scan` once ([Colour filter](/visionstore-docs/scripts/advanced-clothing/guides/colour-filter.md)).

</details>

<details>

<summary>Heritage, face features or hair do nothing</summary>

The player isn't on a freemode model. Those only work on `mp_m_freemode_01` / `mp_f_freemode_01`. Keep `Config.CharacterCreator.initializeNewCharacter = true` so new characters are switched to freemode.

</details>

<details>

<summary>The tattoo catalog is empty</summary>

illenium's `shared/tattoos.lua` couldn't be read (renamed folder or stripped file). Check illenium, or set `Config.Sections.tattoos.source = "custom"` and fill `Config.TattooCatalog`.

</details>

## Outfits, sharing and bags

<details>

<summary>NO OUTFITS AVAILABLE FOR YOUR RANK in a job locker</summary>

The `Config.JobOutfits` key must equal the framework job name (`police`, not `LSPD`), the gender key must be `male` / `female`, and `grades` must include the player's grade number.

</details>

<details>

<summary>OUTFIT NOT COMPATIBLE</summary>

The outfit was made on another ped model (the other gender or a custom ped). Outfits can only be worn on the model they were made on.

</details>

<details>

<summary>INVALID SHARE CODE / SHARE CODE EXPIRED / THAT IS YOUR OWN OUTFIT</summary>

* Invalid: check the characters (no `0`, `O`, `1` or `I`), or the outfit was deleted.
* Expired: `persistentCodes = false` and `expiryHours` passed. Share again.
* Own outfit: codes are for other players; use your wardrobe.

</details>

<details>

<summary>SHARING DISABLED or SAVING DISABLED HERE</summary>

Job and gang lockers and outfit bags don't allow sharing, and lockers don't allow saving. Also check `allowSharing` / `allowSaving` on the entry and `Config.Sharing.enabled`.

</details>

<details>

<summary>Using an outfit bag item does nothing</summary>

The items from `install/ox_inventory_items.lua` are missing in `ox_inventory/data/items.lua`, their `client.export` doesn't say `Chapo_advanced_clothing.useOutfitBag`, or `Config.OutfitBags.enabled = false`. A placed bag with no options means ox\_target isn't started.

</details>

## Custom peds

<details>

<summary>A custom ped comes back as a freemode character after a relog</summary>

Check in this order:

1. `illenium-appearance/game/util.lua` contains the Vision Clothing block (step 4 of [illenium-appearance setup](/visionstore-docs/scripts/advanced-clothing/illenium-setup.md)), often lost after an illenium update.
2. `Config.CustomPeds.enforce = true`.
3. `player_custom_peds` has a row for the character with the right `model` and `verified = 1`.

</details>

<details>

<summary>The game refused to change the ped</summary>

An anticheat is probably blocking `SetPlayerModel`. Whitelist model changes by `illenium-appearance` and `Chapo_advanced_clothing`.

</details>

<details>

<summary>YOUR PED IS STILL LOADING when opening a menu</summary>

The assigned ped is being put on after login or `/giveped`. Wait a moment and open it again.

</details>

Still stuck? [Open a ticket on our Discord](https://discord.gg/ZvHtyhyBp4) with your console errors (see [Support](/visionstore-docs/getting-started/support.md) for what to include).


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://visionstore.gitbook.io/visionstore-docs/scripts/advanced-clothing/troubleshooting.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.