> 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/leisure/cuxial-gym/troubleshooting.md).

# Troubleshooting

Common Cuxial Gym problems, with their cause and fix.

The most frequent problems after installing Cuxial Gym, 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 than the gym. Cuxial Gym needs OneSync, `ox_lib`, `oxmysql`, `cuxial_bridge`, `sleepless_interact` and `cuxial_gym_assets`.

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

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

```cfg
ensure ox_lib
ensure oxmysql
ensure sleepless_interact
ensure cuxial_bridge
ensure cuxial_gym_assets
ensure cuxial_gym
```

{% endcode %}

</details>

<details>

<summary>The equipment is invisible, or exercises have no animation or sound</summary>

**Cause.** `cuxial_gym_assets` is not running, was renamed, or was uploaded incomplete. Props, animations and sounds live there.

**Fix.** Copy `cuxial_gym_assets` again from the original package, keep its folder name and start it before `cuxial_gym`. Restart the server: streamed assets are not always picked up by restarting the resource alone.

</details>

<details>

<summary>There is no gym anywhere after installing</summary>

**Cause.** The sample zone is created only on the first start, when the zones table is empty. If the database was not reachable at that moment, or the zone was deleted later, there is nothing to load.

**Fix.** Run `/gymcreator` and create a zone. `data/seed.lua` is only read on the first start.

</details>

<details>

<summary>/gymcreator or /gymadmin does nothing</summary>

**Cause.** One of these:

* The player has neither the ACE nor the framework permission.
* The module is off: `/gymcreator` needs `modules.creator`; `/gymadmin` needs `modules.admin` and `modules.business`.
* The command was renamed or set to `false` in `commands`.
* The player is training or spotting.

**Fix.** Grant the ACEs and check the config:

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

```cfg
add_ace group.admin cuxial_gym.admin allow
add_ace group.admin cuxial_gym.creator allow
```

{% endcode %}

</details>

<details>

<summary>The equipment says a membership is required</summary>

**Cause.** The zone requires a pass and the player has none.

**Fix.** Buy a pass at the gym menu point, or open the zone in `/gymcreator` and turn the requirement off. Staff can also grant one with the `GrantMembership` export.

</details>

<details>

<summary>The panel or the minigame never shows</summary>

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

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

</details>

<details>

<summary>The panel opens full screen instead of on the gym screen</summary>

**Cause.** The panel is drawn on the screen prop when the player is within `tablet.maxDistance` of one. Otherwise it opens as the full-screen interface.

**Fix.** Use the gym menu from a point that is next to a screen prop. To always use the full-screen interface, set `tablet.dui = false`. Do not change the other values of `tablet`: they match the prop.

</details>

<details>

<summary>Using a supplement does nothing</summary>

**Cause.** The item does not exist in the inventory, or the gym started before the inventory. The console prints `el suplemento "<id>" usa un item que no existe` for each missing item.

**Fix.** Add the eight items of `install/items.lua` to your inventory, start the inventory before `cuxial_gym` and restart the gym.

</details>

<details>

<summary>Items show without an image in the shop or the warehouse</summary>

**Cause.** The image is missing, or your inventory keeps images in another path.

**Fix.** Add `<item>.webp` to your inventory's image folder, or change `items.imageUrl` to the right path. `%s` is replaced by the item name.

</details>

<details>

<summary>Lockers and stashes do not open</summary>

**Cause.** Lockers and stashes require `ox_inventory`.

**Fix.** Use `ox_inventory`, or remove the locker and stash actions from the interaction points.

</details>

<details>

<summary>The cloakroom point does nothing</summary>

**Cause.** The handler points at a resource that is not running. The default one calls `cuxial_appearance`.

**Fix.** Start that resource, or change `cloakroom.handlers` to an export or a client event of your own clothing resource.

</details>

<details>

<summary>The shop, the boss menu or the spotter option is missing</summary>

**Cause.** They belong to the business modules. `modules.business = false` removes all of them; `modules.shop` and `modules.helper` remove each one. A shop point also needs its zone or point to belong to a business.

**Fix.** Turn the modules on, create the business in `/gymadmin` and assign the zone to it.

</details>

<details>

<summary>The daily reward says it is out of stock</summary>

**Cause.** In a zone that belongs to a business, the reward comes out of the business warehouse.

**Fix.** The business has to order or deposit that item in its warehouse.

</details>

<details>

<summary>An employee's worked minutes do not go up</summary>

**Cause.** Minutes only count while the employee is online and inside the work area of the business. A business with no work area counts nothing.

**Fix.** Set the work area of the business in `/gymadmin`.

</details>

<details>

<summary>I changed a data file and nothing changed in game</summary>

**Cause.** That section was saved from an editor at some point. The database copy replaces the file.

**Fix.** Edit it from `/gymcreator` or `/gymadmin`. In the creator, *Reset to defaults* returns a section to the file values.

</details>

<details>

<summary>The gym at the beach looks wrong or has duplicated objects</summary>

**Cause.** `cuxial_gym_assets` includes a map file for that area. Another map resource that edits the same spot conflicts with it.

**Fix.** Run only one of the two maps for that area.

</details>

<details>

<summary>The Discord logs do not arrive</summary>

**Cause.** The convar is not set, or it is set after the gym starts.

**Fix.** Put `set cuxial_gym_webhook "..."` in `server.cfg` above `ensure cuxial_gym`. With debug on, the console tells whether the webhook was read.

</details>

<details>

<summary>Another resource cannot find exports.CuxialGym</summary>

**Cause.** That resource starts before the gym.

**Fix.** Start `cuxial_gym` first. Only `AddSkillToPlayer`, `GetPlayerSkills` and `MaxAllSkills` are meant to be called under that name; use `exports.cuxial_gym` for everything else.

</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/leisure/cuxial-gym/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.