> 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-interactions/troubleshooting.md).

# Troubleshooting

Common Cuxial Interactions problems, with their cause and fix.

The most frequent problems after installing Cuxial Interactions or registering your own NPCs, with the cause and the fix for each one. Console warnings of the resource start with `[cuxial_interactions]`.

<details>

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

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

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

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

```cfg
ensure ox_lib
ensure oxmysql
ensure ox_inventory
ensure cuxial_bridge
ensure cuxial_interactions
```

{% endcode %}

</details>

<details>

<summary>An NPC does not appear</summary>

**Cause.** One of these:

* Its set is off in `sets`, or the point has `enabled = false`.
* The data file has a Lua error. The console shows a warning with the name of the file that could not be loaded.
* The player is further than `spawnDistance` (60 metres by default).
* The ped could not be created. The client console shows a warning with the id of the point.

**Fix.** Set the set to `true` in `shared/config.lua`, fix the error the console points at, and restart the resource. A model that does not exist is replaced by `npc.fallbackModel`; if that one is wrong too, no ped is created.

</details>

<details>

<summary>The NPC is there but there is no option to talk</summary>

**Cause.** One of these:

* No target resource is running, or it starts after Cuxial Interactions.
* The point has a `job`, `item` or `canInteract` condition the player does not meet.
* The point, or the config, has `interaction = 'none'`.
* A dialogue or shop is already open.

**Fix.** Start `sleepless_interact`, `ox_target` or `qb-target` before `cuxial_bridge` and `cuxial_interactions`. Then review the conditions of the point. Points with `interaction = 'none'` only open through the `Interact` export.

</details>

<details>

<summary>I set interaction = 'sprite' and the target is still used</summary>

**Cause.** `bl_sprites` is not running. The client console shows a warning once. Points without a ped always use the target.

**Fix.** Install and start `bl_sprites` before Cuxial Interactions, or go back to `interaction = 'target'`.

</details>

<details>

<summary>The NPC floats or sinks into the ground</summary>

**Cause.** The ped is created at the Z of `coords` plus `npc.zOffset`, which is `-1.0`. That fits coordinates taken from the player's position. Coordinates taken at ground level leave the ped one metre low.

**Fix.** Take the coordinates standing on the spot, or correct the Z of that point. Change `npc.zOffset` only if all your coordinates use another reference.

</details>

<details>

<summary>NPCs with usePlayerSkin all look like the default ped</summary>

**Cause.** One of these:

* The resource in `skins.resource` is not running, so the appearance cannot be applied.
* No character was played in the last `skins.activeDays` days. The server console shows a warning and tries again after `skins.retry` seconds.
* The server runs ESX. `usePlayerSkin` requires QBox or QBCore.

**Fix.** Start `cuxial_appearance` before Cuxial Interactions and raise `skins.activeDays` on a new server. On ESX, give those points a `model`.

</details>

<details>

<summary>The shop says it is not available and nothing can be sold</summary>

**Cause.** The shop is not registered on the server. Either `RegisterShop` was never called, its id differs from `shop.id` on the client, or the registration was rejected: an item without a valid `price`, an empty list, or no `coords`, `netId` or `anywhere`. A rejected registration leaves a warning in the server console.

**Fix.** Call `RegisterShop` with the same id the client uses. In a point registered with `Register`, `shop.id` defaults to the id of the point. Shops written in `data/` are registered automatically when they have an `items` list.

</details>

<details>

<summary>"You are too far from the buyer" while standing next to the NPC</summary>

**Cause.** The server measures the distance to the coordinates given in `RegisterShop`, not to the ped. They are too far from where the player stands, or the distance is too short for that spot.

**Fix.** Register the shop with the coordinates of the NPC, or raise `distance` in the options of that shop. `shop.maxDistance` changes the default for all shops.

</details>

<details>

<summary>The sale fails with "You don't have enough of this item"</summary>

**Cause.** The server counts fewer units than the quantity requested. The item name of the shop does not match the item in `ox_inventory`, or the items left the inventory while the shop was open.

**Fix.** Check that each `name` in the shop is the exact item name of your inventory.

</details>

<details>

<summary>A button does nothing</summary>

**Cause.** Its `onSelect` function failed. The client console shows a warning with the id of the button and the error. In the example sets this happens when a button calls a resource that is not on your server. A `nextDialog` that points to a page that does not exist, or is disabled, also leaves a warning.

**Fix.** Edit the button in its `data/` file, or turn the set off in `sets`. Check that `nextDialog` matches the `id` of a page of the same dialogue.

</details>

<details>

<summary>My NPCs disappear after restarting cuxial_interactions</summary>

**Cause.** Restarting the resource wipes every point and shop registered by other resources.

**Fix.** Register again when it starts, on both sides:

```lua
-- client
AddEventHandler('onClientResourceStart', function(resource)
    if resource == 'cuxial_interactions' then registerNpc() end
end)

-- server
AddEventHandler('onResourceStart', function(resource)
    if resource == 'cuxial_interactions' then registerShop() end
end)
```

</details>

<details>

<summary>Register returns false</summary>

**Cause.** One of these:

* The id is already registered by another resource. The console says which one.
* The definition has none of `coords`, `entity` and `netId`.
* The definition has `enabled = false`.
* `id` is not a string or is empty.

**Fix.** Prefix your ids with the name of your resource and give the point a location.

</details>

<details>

<summary>An icon shows a speech bubble instead of the one I wrote</summary>

**Cause.** The name is not in the icon list of the interface.

**Fix.** Use one of the names listed in [Exports & events](/scripts/core/cuxial-interactions/developers.md). The target option is different: `targetIcon` takes a Font Awesome class.

</details>

<details>

<summary>The dialogue takes a moment to open</summary>

**Cause.** The window waits `camera.settle` milliseconds (1500 by default) so the camera reaches the NPC first.

**Fix.** Lower `camera.settle` and `camera.transition`, or set `camera.enabled = false`.

</details>

<details>

<summary>The paid NPC medic says it cannot attend the player</summary>

**Cause.** The resource in `maria.revive` is not running, or its export did not revive the player. In the first case nothing is charged; in the second the money is returned. The service also refuses when the player is further than `maria.maxDistance` from an NPC of the set in `maria.set`, or when `maria.maxOnDuty` medics are on duty.

**Fix.** Start `cuxial_medical`, or point `maria.revive` to the server export of your medical resource; it is called with the player's server id and must return `true`. Keep the set named in `maria.set` switched on.

</details>

<details>

<summary>The dialogue never shows, or the screen stays focused with nothing on it</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` and the folder `web/dist/assets` exist inside the resource. If they do not, copy the resource again from the original package and restart the server.

</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-interactions/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.