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

# Troubleshooting

Common Cuxial Appearance problems, with their cause and fix.

The most frequent problems after installing Cuxial Appearance, with the cause and the fix for each one.

<details>

<summary>The resource does not start</summary>

**Cause.** A dependency is missing or starts later. Cuxial Appearance needs OneSync, `ox_lib`, `oxmysql` and `cuxial_bridge`.

**Fix.** Enable OneSync and start the dependencies first:

{% code title="server.cfg" %}

```cfg
ensure ox_lib
ensure oxmysql
ensure cuxial_bridge
ensure cuxial_appearance
```

{% endcode %}

</details>

<details>

<summary>The menu never shows, or the screen stays empty with the cursor visible</summary>

**Cause.** The interface is not loading. The folder `web/build` is missing or incomplete, usually after a partial upload.

**Fix.** Make sure `web/build/index.html` exists inside the resource. If it does not, copy the resource again from the original package and restart the server.

</details>

<details>

<summary>The console shows failed queries on the appearance or outfits tables</summary>

**Cause.** The database already had a table named `appearance` or `outfits` from another script, with different columns. The resource does not replace an existing table.

**Fix.** Stop the server, back up the database, rename or remove the old tables and start again so they are created with the right columns. Then bring the old looks in with the migration command if it supports your previous script.

</details>

<details>

<summary>I changed a price in shared/config.lua and nothing changed</summary>

**Cause.** `prices`, `secondHand`, `ui.menuAlpha` and part of `wardrobe` and `trimmer` are stored in the database on first start. From then on the database wins over the file.

**Fix.** Change the value in the staff panel, section settings. To go back to the values of the file, edit the file, restart the resource and use the reset button of that block.

</details>

<details>

<summary>I edited data/shops.lua and the shops did not change</summary>

**Cause.** That file is only read when the shop table is empty, on first start.

**Fix.** Edit shops from the staff panel. The import button adds the shops of the file that are missing by name; it does not change the ones that exist.

</details>

<details>

<summary>The console says the garment item is not registered, and taking a garment off fails</summary>

**Cause.** The item of `wardrobe.item` does not exist in your inventory.

**Fix.** Add the items of the [Installation](/scripts/core/cuxial-appearance/installation.md) page and restart the inventory and the resource. The name in the inventory must match the config.

</details>

<details>

<summary>Using a garment item does nothing</summary>

**Cause.** The item has no use handler.

**Fix.** In `ox_inventory`, the item needs `client = { export = 'cuxial_appearance.useClothing' }`. The resource folder must be named `cuxial_appearance`.

</details>

<details>

<summary>The clothing panel, garment bags or body search are missing</summary>

**Cause.** Inventory mode is off, or the convar was set with `set` and the client cannot read it.

**Fix.** Use `setr` and restart the server:

{% code title="server.cfg" %}

```cfg
setr cuxial_appearance:inventory 1
```

{% endcode %}

Inventory mode also needs an inventory that provides the clothing panel and the garment bag containers.

</details>

<details>

<summary>The photo studio says the server does not know the photos resource</summary>

**Cause.** `cuxial_appearance_photos` is not in the `resources` directory, or the server has not scanned it.

**Fix.** Copy the resource, then run `refresh` and `ensure cuxial_appearance_photos` in the server console. Add the `ensure` line to `server.cfg`.

</details>

<details>

<summary>The photo studio says the server cannot write into the photos resource</summary>

**Cause.** The filesystem permission is missing.

**Fix.** Add this line to `server.cfg` and restart the server:

{% code title="server.cfg" %}

```cfg
add_filesystem_permission cuxial_appearance write cuxial_appearance_photos
```

{% endcode %}

</details>

<details>

<summary>The photo studio closes at once with an error about captures</summary>

**Cause.** No capture resource is running.

**Fix.** Start `screencapture` or `screenshot-basic` before Cuxial Appearance, or set the name of yours in `photos.captureResource`.

</details>

<details>

<summary>Photos are taken but the catalogue shows none</summary>

**Cause.** The photos resource is not started, or it was not restarted after the session, so clients do not have the new files.

**Fix.** Check that `cuxial_appearance_photos` is running. The studio restarts it on finish; if the console reports that the command was refused, restart it by hand with `ensure cuxial_appearance_photos`, or allow it:

{% code title="server.cfg" %}

```cfg
add_ace resource.cuxial_appearance command.ensure allow
```

{% endcode %}

</details>

<details>

<summary>Photos show the previous garment or a half-loaded one</summary>

**Cause.** The capture happens before the garment has finished loading.

**Fix.** Raise `photos.waitApply` and `photos.waitCapture`, flag the wrong photos and run the session again.

</details>

<details>

<summary>Staff commands answer that I am not allowed</summary>

**Cause.** Your framework does not grant you the permission of `admin.permission`.

**Fix.** Give yourself that permission in your framework, or change `admin.permission` to one you have. On ESX, `'admin'` accepts the groups `admin` and `superadmin`. If you set `restricted` on a command, you also need that ACE.

</details>

<details>

<summary>The trimmer says it needs the emote system</summary>

**Cause.** `cuxial_emotes` is not running, or the emote of `trimmer.emote` does not exist in it.

**Fix.** Start `cuxial_emotes` before Cuxial Appearance and check the emote name.

</details>

<details>

<summary>A player cannot change their hair</summary>

**Cause.** They were shaved with the trimmer. Hair is locked for `trimmer.hairLockMinutes`.

**Fix.** Wait, or lower the value in the staff panel. `0` removes the lock for future shaves.

</details>

<details>

<summary>The tattoo tab is missing</summary>

**Cause.** `rcore_tattoos` is running. Cuxial Appearance leaves tattoos to it and hides its own tab. The tab only exists in the `appearance` menu.

**Fix.** To use the built-in tattoos, stop `rcore_tattoos`.

</details>

<details>

<summary>The placed outfit bag cannot be opened</summary>

**Cause.** No target resource is running, or `cuxial_bridge` picked a different one.

**Fix.** Start `sleepless_interact`, `ox_target` or `qb-target` before `cuxial_bridge`.

</details>

<details>

<summary>Characters from my old clothing script appear with the default look</summary>

**Cause.** Their skins have not been imported.

**Fix.** Keep `compat.legacySkins = true` to import each one when it is first needed, or run the migration command once. See [Commands & permissions](/scripts/core/cuxial-appearance/commands.md#migration).

</details>

<details>

<summary>I changed menu.openControl but the shop still opens with the old key</summary>

**Cause.** `menu.openControl` is only the default. Once a player has joined, FiveM remembers their key binding.

**Fix.** Each player changes it in the GTA settings, under key bindings, FiveM.

</details>

<details>

<summary>A new character is not sent to the creator</summary>

**Cause.** Nothing calls the creator. Cuxial Appearance does not open it by itself.

**Fix.** Your multicharacter resource has to call `exports.cuxial_appearance:InitialCreation()` or trigger `qb-clothes:client:CreateFirstCharacter` for new characters. See [Exports & events](/scripts/core/cuxial-appearance/developers.md#initialcreation).

</details>


---

# 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://docs.cuxial.com/scripts/core/cuxial-appearance/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.