> 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/weaponhub/troubleshooting.md).
# Troubleshooting
Fixes for the most common problems.
{% hint style="info" %}
First step, always: look at the **server console**. The hub prints a warning for most setup problems when it starts. Set `Config.Debug = true` to see the workbench zones in game.
{% 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.
"N base-game attachments have no ox_inventory item yet"
`install/ox_inventory_items.lua` isn't in `ox_inventory/data/weapons.lua`, or ox\_inventory was updated and the file was replaced. Paste it again ([Installation](/visionstore-docs/scripts/weaponhub/installation.md)) and restart ox\_inventory, then the hub.
"no ox_inventory item fits WEAPON_X COMPONENT_Y"
A part from `config/weapons.lua` has no item that resolves to it on that weapon. Add it to an item's `client.component` list or make a new item ([Giving a part an item](/visionstore-docs/scripts/weaponhub/guides/add-on-weapons.md#giving-a-part-an-item)). On one weapon an item is only ever its **first** matching part, so two scopes of the same weapon can't share one item.
"... is pinned to item ..., but that item's client.component list does not contain it"
An `item = '...'` in `config/weapons.lua` names an item that can't fit that part. Add the part to the item's list in ox\_inventory, or remove the `item` pin.
The console says "running standalone" but I use a framework
The hub started before your framework. Move `ensure vision_weaponhub` **below** your framework in `server.cfg`, or set `Config.Framework` to `'qbx'`, `'qb'`, `'esx'` or `'ox'` explicitly.
## Workbenches
The workbench prompt doesn't appear
* With `Config.Target = 'auto'`, the target resource must start **before** the hub.
* `jobs` / `items` on the bench hide the ox\_target option from players who don't match.
* Ammu-Nation MLO: the default bench coordinates are for the base-game shop. Move it with `/weaponhub_here`.
"You moved too far from the workbench"
The player walked further than `Config.MaxDistance` (4 m) from where the bench opened. Raise it for big benches, or put the bench `coords` closer to where players stand.
"You cannot afford the fee"
The fee is taken from the account in the settings (`cash` / `bank`). On ESX, cash is the `money` account. On ox\_core and standalone, cash is the ox\_inventory `money` item.
"This is issued equipment"
The weapon or part has the `Config.IssuedEquipment.key` metadata flag and the player isn't in one of its jobs. Set `key = false` to turn the rule off, or adjust `jobs`.
/weaponhub does nothing
Your account needs the ace `vision_weaponhub.admin` or one of `Config.Admin.groups`. Check that `server.cfg` contains `add_ace group.admin vision_weaponhub.admin allow` and that you're in `group.admin`. Also check `Config.Admin.commands` is `true`.
## Weapons and parts
A weapon isn't in the list
The hub lists the weapons the player carries that are ox\_inventory weapon items, aren't throwables, and aren't in `Config.Blacklist`. Weapons without attachment points still open for tints. Is the item name in ox\_inventory exactly the weapon name (`WEAPON_...`)?
A part shows "Incompatible"
The weapon model doesn't accept it. With add-on weapons, the pack's `weaponcomponents.meta` may not be loaded, or the component name in `config/weapons.lua` has a typo. Run the [helper](/visionstore-docs/scripts/weaponhub/guides/add-on-weapons.md) on the pack instead of typing names.
The part is fitted in the hub but not on the gun in hand
ox\_inventory fits parts when the gun is drawn. Holster and draw it again. If it's still missing, the item's `client.component` list on the **client** differs from the server (an old cached `data/weapons.lua`): restart ox\_inventory.
Two magazines (or finishes) show at once on the gun in hand
The hub removes the leftover factory part after ox\_inventory draws the gun. If another script re-adds components afterwards, it wins. Check scripts that also give weapon components.
No tints, or fewer than expected
Check `Config.Tints.enabled`, the weapon's palette (`Config.WeaponTints`), and the model: colours above the weapon model's own tint count are hidden. Most add-on weapons have 8 or 32.
No Camo Colour grid
Only weapons with an MK II camo slot have one, and `Config.Livery.enabled` must be `true`. The colour is visible once a camo is fitted or staged.
## Display
The screen goes dark / the backdrop is missing
The studio backdrop is drawn by a DUI (an off-screen browser). Set `Config.Stage.enabled = false` to place the weapon in front of the player at the bench instead. A custom photo must be in `stage/`.
The interface doesn't open (focus but nothing visible)
`web/dist` must be present. It ships built: don't delete it.
The player stays invisible or frozen
Only while the hub is open (`Config.Preview.hidePlayer`). The hub closes, and restores everything, on death, ragdoll, entering a vehicle, walking away, Escape, and resource stop.
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/weaponhub/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.