> For the complete documentation index, see [llms.txt](https://visionstore.gitbook.io/visionstore-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://visionstore.gitbook.io/visionstore-docs/scripts/badges/troubleshooting.md).
# Troubleshooting
Fixes for the most common problems.
{% hint style="info" %}
First step, always: look at the **server console**. At start the script prints what it detected:
`[vision_badges] v1.0.0 ready | framework: qbx | inventory: ox_inventory | 9 badge types | 2 desks`
Problems in the `config/` files are printed as warnings too, starting with `[vision_badges]`.
{% endhint %}
## Startup
"You lack the required entitlement" / the resource won't start
See [Escrow and common errors](/visionstore-docs/getting-started/escrow-and-common-errors.md). The server key must belong to the account that bought the script.
The console shows the wrong framework, inventory or none
The script started before them. Move `ensure vision_badges` **below** your framework, inventory and target resource in `server.cfg`, or set `Config.Framework`, `Config.Inventory` or `Config.Target` explicitly.
item "vision_badge" is not registered in ...
The item is missing from your inventory. Issuers see "The badge item is not installed. Please tell an admin." Add it as shown in [Installation](/visionstore-docs/scripts/badges/installation.md) and restart the server. A badge with its own `item = '...'` needs that item registered too.
could not create the badge tables
Your database user can't create tables. Import `install/vision_badges.sql` manually, then restart.
## Desks and issuing
The desk option isn't visible
1. **Can you issue this badge?** You must be an admin, be in the badge's `issuerIds`, or have the right **active** job / gang and grade. Job names must match your framework exactly. On a multi-job character, switch to the job first.
2. **Duty:** with `requireDuty = true` you must be on duty.
3. **Does the desk serve the badge?** The badge id must be in the desk's `badges`, and both must be enabled.
4. **Right spot?** Moved Mission Row or Pillbox to an MLO? Update the desk coordinates. `Config.Debug = true` draws the zones.
5. **Rights changed while online?** Reconnect. On standalone, desk options are worked out when you join.
"Issue my own ... badge" missing: `Config.Issuing.AllowSelf` is `false`, or you don't hold one of the badge's `jobs` yourself (this applies to admins too).
I get an [E] prompt instead of a target option
ox\_target or qb-target started after Vision Badges Creator. Fix the start order in `server.cfg`.
"Nobody is close enough to receive a badge."
The badge goes to the **nearest** player within 3 m (`Config.Issuing.NearestDistance`), in the same routing bucket. Bring the recipient closer. To issue your own, use **Issue my own ... badge** or `/issuebadge self`.
Other issuing messages
| Message | Cause |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| "You are not allowed to do that." | Not an issuer of this badge, the desk doesn't serve it, or `/issuebadge` without admin rights while `Command.anywhere = false`. |
| "You have to stand at the badge desk." | Too far from the desk centre (radius + 2.5 m). |
| "That person is not a member of ..." | The recipient holds none of the badge's `jobs`. |
| "They already carry a valid badge with the same rank." | `BlockIfCarrying`. After a promotion the re-issue works. |
| "Wait N seconds before issuing another badge." | `Config.Issuing.Cooldown`. |
| "Their pockets are full." | The recipient's inventory has no room. |
| "The recipient walked away, the badge was not issued." | They moved away while the review panel was open. |
| "The request expired, please start again." | The review panel stayed open longer than 60 s. |
| "The server did not answer, please try again." | Check the server console. |
| "The badge could not be saved. Please tell an admin." | Database error. Check that the tables exist and oxmysql is connected. |
"The photo could not be taken, please try again."
Click **Retake photo** first. Common causes:
* the recipient isn't fully visible or streamed yet: stand close, face each other;
* another resource uses up GTA's ped headshots: restart that resource or reconnect;
* the image is larger than `Config.Photo.MaxLength`: lower `Quality`, keep `Format = 'image/webp'`, or raise `MaxLength`.
Don't need photos? Set `Config.Photo.Required = false`: the card then shows "NO PHOTO" when the capture fails.
## Showing badges
Using the item does nothing
* **ox\_inventory:** the item entry must contain `server = { export = 'vision_badges.useBadge' }`, and the folder must be named exactly `vision_badges`.
* **"This badge is blank."** The item was spawned with a give-item command, so it carries no badge data. Issue badges at a desk or with `/issuebadge`.
* **"This badge is damaged and cannot be shown."** The badge type was deleted or renamed, or its `item` was changed after issuing. Create the type again with the same id, or set `item` back.
A badge shows INACTIVE
The owner no longer holds any of the badge's `jobs` (fired, changed job, or the `jobs` list changed). After a rehire it can stay INACTIVE for up to 60 seconds (`Config.Validity.CacheSeconds`). Set `Config.Validity.CheckMembership = false` to turn the check off.
A badge shows REVOKED or UNREGISTERED
* **REVOKED:** voided in the Registry, by an export, or replaced by a newer badge of the same type. Issue a new one.
* **UNREGISTERED:** the item points to a badge record that doesn't exist or belongs to someone else. Issue a new one.
Showing a badge fails
| Message / symptom | Cause |
| ------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| "You cannot show a badge right now." | Dead, downed or cuffed. |
| "Wait N seconds before showing your badge again." | `Config.Present.Cooldown`. |
| "This badge is not yours." | `Config.Present.OwnerOnly = true`. |
| "You have no badge to show." | `/badge` found no badge to show. |
| Nobody else sees it | `ShowToNearby` is off, or nobody is within 3.5 m in your routing bucket. |
| No prop in the hand | `Prop = false`, a wrong model, or a badge `present.prop` missing `bone`, `pos` or `rot`. |
## Studio and config
The Studio says "You are not allowed to do that"
You're not an admin for this script. Add the ace (rights are checked live, no restart needed):
```properties
add_ace group.admin vision_badges.admin allow
add_principal identifier.license:YOUR_LICENSE group.admin
```
`/badgestudio` is an unknown command? `Config.Admin.studioCommand` is `false` or renamed.
My config change isn't applied
1. **Restart the resource** after editing `config/`: `restart vision_badges`.
2. **The Studio override wins.** If the badge or desk is tagged **EDITED**, click **Reset to file** in the Studio.
3. **Studio badges store their full look.** Editing a preset doesn't change them: click **Apply** on the preset again.
4. **Issued items keep their inventory label, icon and tooltip.** The badge itself always shows the current design.
5. **Close key:** a new `CloseKey` only reaches players who never had the binding.
6. Look for a warning in the console: invalid values are dropped and replaced by defaults.
My custom logo doesn't show
* The file must be in `web/logos/`, and the badge names only the file: `logo = 'lsc.png'`.
* Letters, digits, `_` and `-`, no spaces, ending in `.png`, `.webp`, `.svg`, `.jpg` or `.jpeg`.
* **Restart the resource after adding a file.**
Still stuck? [Open a ticket on our Discord](https://discord.gg/ZvHtyhyBp4) with your console errors (see [Support](/visionstore-docs/getting-started/support.md) for what to include).
---
# 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://visionstore.gitbook.io/visionstore-docs/scripts/badges/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.