> 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/interface/cuxial-emotes/troubleshooting.md).
# Troubleshooting
Common Cuxial Emotes problems, with the cause and the fix for each one.
Most problems come from a missing dependency, the start order or the add-on not running. Find your symptom below.
## Startup
The resource does not start: "Could not find dependency"
**Cause.** One of the resources declared in the manifest is missing or stopped: `ox_lib`, `oxmysql` or `cuxial_bridge`. OneSync is also required.
**Fix.** Install the missing resource and start it before `cuxial_emotes`. Enable OneSync on the server.
```cfg
ensure ox_lib
ensure oxmysql
ensure cuxial_bridge
ensure cuxial_emotes
```
Exports or items fail with "No such export"
**Cause.** The folder was renamed. Other resources and the inventory items call the resource by its name.
**Fix.** Name the folder `cuxial_emotes` again.
The console warns that cuxial_emotes_dlc is installed but not started
**Cause.** The add-on folder is on the server but it is not running.
**Fix.** Add `ensure cuxial_emotes_dlc` above `ensure cuxial_emotes` in `server.cfg`. Until then, zones and relations stay off.
Database errors in the console on start
**Cause.** `oxmysql` is not connected, or the database user cannot create tables.
**Fix.** Check the connection string and the user's permissions. As an alternative, create the tables by hand with `install/emotes.sql`.
## Menu
The menu does not open with F3
**Cause.** The key is stored per player, so someone with a different binding keeps their own. The menu also stays closed while the player is dead or locked by another resource through `SetEmoteLock`.
**Fix.** Rebind it in the GTA settings, under key bindings for FiveM ("Open Animations Menu").
The menu opens blank or does not appear at all
**Cause.** The interface files are missing. The resource loads `web/dist/index.html`.
**Fix.** Check that `web/dist` exists and has files. If it is empty or incomplete, copy the resource again from the original package.
I changed a key in the config and nothing changed
**Cause.** `keys` only sets the default for players who have never joined with the resource. FiveM remembers each player's binding.
**Fix.** Each player changes it in their GTA settings. Do not rename `commands.menu.name` to force it: that resets the key for everyone.
A new emote or category does not appear in the menu
**Cause.** The category file is not listed in `data/manifest.lua`, or the file has a Lua error.
**Fix.** Add the file name to `categories`, check the console for Lua errors and restart the resource.
An emote is not marked as new
**Cause.** The `Added` field is missing, is not in `'YYYY-MM-DD'` format, or is older than `ui.newEmoteDays`.
**Fix.** Set the date correctly or raise `ui.newEmoteDays`.
## Emotes
An emote does nothing
**Cause.** One of these applies:
* the player is dead and `deadCheck.enabled` is `true`;
* the player is in a vehicle and `emotes.disableInCar` is `true`;
* less than `commands.emote.cooldown` milliseconds passed since the last emote;
* another resource locked the player with `SetEmoteLock`, or blocked emotes with `SetCanPlayAnimation(false)` or the `isLimited` state.
**Fix.** Check which case applies. If another resource set a lock and never released it, restart that resource.
A custom emote does not play, but the menu shows it
**Cause.** The animation dictionary is not streamed, `Dictionary` and `Animation` are swapped, or another emote already uses the same `Command`.
**Fix.** Put the `.ycd` file in the resource's `stream/` folder and restart the server. The dictionary is the name of the `.ycd`; the animation is the clip inside it. Make sure the `Command` is unique.
A prop is missing or other players do not see it
**Cause.** The prop model is not streamed, or the emote has more props than `emotes.maxProps`.
**Fix.** Check the model name in `Options.Props` and raise `emotes.maxProps` if the emote needs more.
Dead players can still use emotes
**Cause.** `deadCheck.useStateBag` is `true` but your medical script does not set the `dead` state on the player.
**Fix.** Set `deadCheck.useStateBag = false` so the script asks the game instead.
Walk style or expression is lost after reconnecting
**Cause.** The matching option in `saving` is `false`.
**Fix.** Set `saving.walkStyle` and `saving.expression` to `true`.
Crouch behaves oddly or toggles twice
**Cause.** Another resource also handles crouching on the same key.
**Fix.** Disable crouch in the other resource, or have players rebind one of the two keys.
## Paired emotes
"No one nearby"
**Cause.** No player within `sync.distance`, or the emote has no valid `Options.Shared.OtherEmote`.
**Fix.** Get closer or raise `sync.distance`. For a custom emote, check that `OtherEmote` points to an existing command.
"That player already has a pending request"
**Cause.** The other player has an unanswered request.
**Fix.** Wait for them to answer, or for it to expire after `sync.pendingMs`.
The two characters end up misaligned
**Cause.** The offsets of that paired emote are off.
**Fix.** Run `/syncpos [receiver]` and adjust the position. The command copies a `Shared = { ... }` block: paste it into the emote's `Options`, replacing the old one.
## Zones and staff
/emotezones does nothing
**Cause.** One of these is missing:
* the player is not in the ACE group set in `commands.zones.restricted`;
* the player lacks the `cuxial_bridge` permission set in `admin.permission`;
* the `cuxial_emotes_dlc` add-on is not running.
**Fix.** Grant the group and the permission, and start the add-on before Cuxial Emotes.
Zone emotes show up everywhere, or never
**Cause.** `zones.global` is `true` (everywhere), or the zone is disabled or has no emotes assigned (never).
**Fix.** Set `zones.global = false` and review the zone in `/emotezones`.
## Reports and relations
Reports do not reach Discord
**Cause.** The webhook convar is empty or has a different name than `report.convar`.
**Fix.** Add it to `server.cfg` and restart the server. Reports are saved in `cuxial_emote_reports` either way.
```cfg
set cuxial_emotes:report_webhook "https://discord.com/api/webhooks/..."
```
The relations items do nothing when used
**Cause.** The `cuxial_emotes_dlc` add-on is not running. Without it the item exports exist only so the inventory does not error.
**Fix.** Start the add-on before Cuxial Emotes. Tests also need the optional `cuxial_diseases` running. Without it they do nothing.
---
# 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/interface/cuxial-emotes/troubleshooting.md?ask=&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.