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

# Troubleshooting

Common Cuxial License problems, with their cause and fix.

The most frequent problems after installing Cuxial License, 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 License needs `ox_lib`, `oxmysql`, `cuxial_bridge` and `screencapture`. The last one is the usual culprit: it is not part of a default server.

**Fix.** Install `screencapture` as explained in [Installation](/scripts/core/cuxial-license/installation.md#install-screencapture) and start everything in order:

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

```cfg
ensure ox_lib
ensure oxmysql
ensure cuxial_bridge
ensure screencapture
ensure cuxial_license
```

{% endcode %}

</details>

<details>

<summary>The capture never finishes, or the console shows an error about screencapture</summary>

**Cause.** `screencapture` is running from the source code instead of a packaged release, its folder has another name, or the server artifact is too old for it.

**Fix.** Download the packaged release again, make sure the folder is called `screencapture` and contains `game/dist`, and update the server artifact. If captures still fail with your hosting provider, open the `fxmanifest.lua` of `screencapture` and read the note next to its `protocol` line.

</details>

<details>

<summary>Cards are issued without a photo</summary>

**Cause.** One of these:

* The convar `cuxial:fivemanageToken` is empty, misspelled or set after the resource starts. It is read once, on start.
* The token is not valid for images, so the upload is rejected.

**Fix.** Add the convar above `ensure cuxial_license` and restart the server:

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

```cfg
set cuxial:fivemanageToken "YOUR_FIVEMANAGE_TOKEN"
```

{% endcode %}

Cards issued while the token was missing keep having no photo. Issue them again.

</details>

<details>

<summary>The photo has the scenery behind the character</summary>

**Cause.** The player was not in front of a green backdrop. Either `photo.greenScreenPos` points somewhere else, or the `stream` folder of the resource is incomplete and the room was not loaded.

**Fix.** Restore the default `greenScreenPos`, or copy the resource again from the original package, and restart the server.

</details>

<details>

<summary>Using the card does nothing</summary>

**Cause.** One of these:

* The item is not defined with `client.export = 'cuxial_license.useLicenseCard'`.
* The card design uses another item name and that item has no definition.
* The resource folder was renamed, so the export no longer exists.
* The item was spawned by hand. Only cards issued by the script carry the data needed to show them.
* The card design was deleted.

**Fix.** Review the items in [Installation](/scripts/core/cuxial-license/installation.md#add-the-items), keep the folder name `cuxial_license`, and issue the card through the office, `/jobissue` or the `IssueLicense` export.

</details>

<details>

<summary>"This document has expired. You need to get a new one."</summary>

**Cause.** The item carries no owner data. It happens with items added by another resource without the owner's name.

**Fix.** Issue the card again and throw the old item away.

</details>

<details>

<summary>/license is denied</summary>

**Cause.** The player lacks the framework permission in `admin.permission`.

**Fix.** Give the player that permission in your framework, or change `admin.permission` to one they have.

</details>

<details>

<summary>"Your job is not authorized for this action."</summary>

**Cause.** The player's job is not in `authorizedJobs`, or their grade is below the minimum. The example values in the file ask for grade 4.

**Fix.** Add the job with the grade you want in `shared/config.lua`. The key is the job name, not its label.

</details>

<details>

<summary>The office NPC is missing or cannot be interacted with</summary>

**Cause.** The coordinates in `zones` are not where you expect, the ped model does not exist, or no target resource is running.

**Fix.** Check `coords` and `model`, and start a target resource supported by `cuxial_bridge` before the bridge. Restart the resource after changing the config.

</details>

<details>

<summary>The store says there are no licences available</summary>

**Cause.** The store only lists cards with **Charge money** enabled and without **Restrict to job**.

**Fix.** Edit the card with `/license` and enable **Charge money** in the last step. The amount can be 0.

</details>

<details>

<summary>The player never gets the photo request</summary>

**Cause.** The player already had one of the script's panels open, or 60 seconds went by. The agent sees "Photo session expired".

**Fix.** Ask the player to close what they have open and issue the card again.

</details>

<details>

<summary>Nearby players do not see the card I show</summary>

**Cause.** They are further than `showRadius`, or they are already looking at another card.

**Fix.** Get closer or raise `showRadius`.

</details>

<details>

<summary>The time-of-day selector in the photo studio does nothing</summary>

**Cause.** The selector works through `av_weather`, and it is not running.

**Fix.** Start `av_weather`. The photo itself does not depend on it.

</details>

<details>

<summary>The wanted and dangerous marks never appear</summary>

**Cause.** They come from `cuxial_police`, and it is not running.

**Fix.** Start `cuxial_police`. Without it the cards are shown with no marks.

</details>

<details>

<summary>Licences disappeared after deleting a card design</summary>

**Cause.** Deleting a design removes every licence issued from it.

**Fix.** It cannot be undone from the game. Create the design again and issue the cards again, or restore a database backup.

</details>

<details>

<summary>Database errors when the resource starts</summary>

**Cause.** The database user cannot create tables.

**Fix.** Run `sql/install.sql` by hand, then restart the resource.

</details>

<details>

<summary>The panels do not open</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` and `web/build/assets` exist inside the resource. If they do not, copy the resource again from the original package and restart the server.

</details>

<details>

<summary>Texts appear in the wrong language</summary>

**Cause.** The script follows the `ox:locale` convar.

**Fix.** Set it in `server.cfg` and restart. `en` and `es` are included:

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

```cfg
setr ox:locale "en"
```

{% endcode %}

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