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

# Troubleshooting

Common Cuxial Garages problems, with their cause and fix.

The most frequent problems after installing Cuxial Garages, with the cause and the fix for each one.

## Start-up

<details>

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

**Cause.** A dependency is missing or starts later than the garages. Cuxial Garages needs OneSync, `ox_lib`, `oxmysql` and `cuxial_bridge`.

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

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

```cfg
ensure ox_lib
ensure oxmysql
# your framework here
ensure ox_inventory
ensure cuxial_bridge
ensure cuxial_garages
```

{% endcode %}

</details>

<details>

<summary>The console never prints the <code>[cuxial_garages][mysql]</code> line, or shows a SQL error on start</summary>

**Cause.** The tables could not be created. They reference the vehicle table of your framework (`player_vehicles` on QBox and QBCore, `owned_vehicles` on ESX), so that table must exist first.

**Fix.** Check that `oxmysql` connects to the database and that the framework is installed with its own SQL. Start `cuxial_garages` after the framework and `cuxial_bridge`.

</details>

<details>

<summary>Importing the sample SQL fails with "table doesn't exist"</summary>

**Cause.** The files in `install/` were imported before the first start. The tables are created by the resource, not by those files.

**Fix.** Start the server once, import the files, then restart `cuxial_garages`.

</details>

<details>

<summary>The interface does not open: the prompt appears but nothing shows</summary>

**Cause.** The folder `web/build` is missing or incomplete, usually after a partial upload.

**Fix.** Copy the resource again from the package you downloaded, including the whole `web/build` folder, and restart it.

</details>

## Garages

<details>

<summary>There are no markers or blips on the map</summary>

**Cause.** A new install has no garages. Other possible causes: a job garage is only shown to players with that job, and blips are hidden with `blips.garages = false`.

**Fix.** Create garages with `/garageadmin`, or import the sample data from `install/`. Check `blips` in `shared/config.lua`.

</details>

<details>

<summary>The marker is a small blue arrow instead of the garage icon</summary>

**Cause.** The marker texture could not be loaded. The file `stream/cuxial_garage.ytd` is missing, or `marker.textureDict` in `data/zones.lua` was changed.

**Fix.** Copy the `stream` folder again from the package, restore `marker.textureDict` to `'cuxial_garage'` and restart the resource.

</details>

<details>

<summary>A vehicle appears in the list but cannot be taken out</summary>

**Cause.** A vehicle is taken out at the garage where it is stored. From another garage it has to be transferred first. The access point must also accept its category (car, motorcycle, air or sea).

**Fix.** Use the transfer option to bring it to the garage you are at, or go to the garage shown on the vehicle.

</details>

<details>

<summary>After moving from another garage script, vehicles show as outside or cannot be found</summary>

**Cause.** The old script used other state values, or saved garage ids that do not exist any more.

**Fix.** Set `normalizeStatesOnStart = true` for one start so every vehicle with an unknown state becomes stored, then set it back to `false`. Put the id of a public garage in `fallbackGarage` to receive the vehicles whose garage no longer exists.

</details>

<details>

<summary>"That garage is full" although there are free spots</summary>

**Cause.** With `capacity.enabled = true` the limit counts every vehicle the player keeps in that garage, including the ones currently outside.

**Fix.** Raise the capacity of the garage in the admin panel, or set `capacity.enabled = false`.

</details>

<details>

<summary>The house garage export does nothing</summary>

**Cause.** `externalGarages` is `false`, or the player is more than `interactDistance` away from the `coords` sent by the housing resource.

**Fix.** Set `externalGarages = true` in `shared/config.lua` and call the export with the position of the garage door, next to the player.

</details>

## Keys

<details>

<summary>No key arrives when taking a vehicle out, and the engine will not start</summary>

**Cause.** The key item is not registered in the inventory, or its name does not match `item` in `data/keys.lua`. Without a key the engine is switched off.

**Fix.** Add `vehiclekeys` to `ox_inventory/data/items.lua` as shown in [Installation](/scripts/core/cuxial-garages/installation.md), and restart `ox_inventory` and `cuxial_garages`.

</details>

<details>

<summary>Keys stack and open the wrong vehicle</summary>

**Cause.** The item was added without `stack = false`.

**Fix.** Set `stack = false` on `vehiclekeys` and `rentalticket`.

</details>

<details>

<summary>Players get two keys, or another script cannot give keys</summary>

**Cause.** Another vehicle key resource is running. Cuxial Garages answers the `qbx_vehiclekeys` calls itself.

**Fix.** Remove the other key resource from `server.cfg`. To keep it instead, set `enabled = false` in `data/keys.lua`.

</details>

<details>

<summary>The lockpick does nothing</summary>

**Cause.** The player is more than 2.5 metres from the vehicle, the vehicle is not locked, or the player already has access to it.

**Fix.** Stand next to a locked vehicle. Check that the item names match `lockpick.normal.item` and `lockpick.advanced.item`.

</details>

<details>

<summary>The police never get theft alerts</summary>

**Cause.** The resource in `dispatch.resource` is not running, or the alert was skipped by `chance`, `nightChance` or `cooldown`. The night is measured with the real clock of the server.

**Fix.** Start the dispatch resource before testing and raise `chance` and `nightChance` to `1.0` while you test.

</details>

## Staff

<details>

<summary><code>/garageadmin</code> answers that you have no permission</summary>

**Cause.** Your framework does not grant you the permission in `admin.permission`.

**Fix.** Give yourself that permission in your framework, or change `admin.permission` to one you already have.

</details>

<details>

<summary><code>/adminkey</code> or <code>/carwipe</code> are refused although the panel opens</summary>

**Cause.** These commands check an ACE group, not the framework permission.

**Fix.** Add yourself to the group:

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

```cfg
add_principal identifier.license:xxxxxxxxxxxxxxxx group.admin
```

{% endcode %}

</details>

<details>

<summary>A cleanup removes job or rental vehicles</summary>

**Cause.** Fleet vehicles and rentals have no owner in the database, so the cleanup treats them as abandoned unless a player is inside.

**Fix.** Add the places where they are parked to `protectedZones` in `data/carwipe.lua`, or set `deleteNPCVehicles = false`.

</details>

## Rentals and impound

<details>

<summary>The rental contract does not arrive in the inventory</summary>

**Cause.** `rentalticket` is not in the inventory items, or its name does not match `ticketItem` in `data/rental.lua`.

**Fix.** Add the item as shown in [Installation](/scripts/core/cuxial-garages/installation.md). To rent without a contract item, set `giveTicketItem = false`.

</details>

<details>

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

**Cause.** The rental has ended or the vehicle was already returned. The receipt only opens for active contracts.

**Fix.** None needed. The item can be thrown away.

</details>

<details>

<summary>The licence selector is disabled, or licensed offers are locked for everyone</summary>

**Cause.** The resource in `license.resource` is not running.

**Fix.** Start it before `cuxial_garages`, or remove the licence from the offers in the admin panel.

</details>

<details>

<summary>Rental warnings arrive as notifications instead of mail</summary>

**Cause.** `lb-phone` is not running, or the player has no phone equipped.

**Fix.** None needed: the notification is the fallback.

</details>

<details>

<summary><code>/impound</code> answers that the vehicle cannot be impounded</summary>

**Cause.** The player's job is not in `jobs` of `data/impound.lua`, or the vehicle is further than `maxDistance`.

**Fix.** Add the job to `jobs` and stand next to the vehicle.

</details>

<details>

<summary>The owner cannot retrieve an impounded vehicle</summary>

**Cause.** The vehicle is held at another depot, or the officer blocked self-retrieval in the impound form.

**Fix.** Go to the depot named on the vehicle. If self-retrieval was blocked, a member of a job with access to that depot has to release it.

</details>

## Language

<details>

<summary>The interface is in one language and the notifications in another</summary>

**Cause.** They are set in two places. The interface uses `language` in `shared/config.lua`; notifications, prompts and command help use the convar `ox:locale`.

**Fix.** Set both to the same language:

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

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

{% endcode %}

{% code title="shared/config.lua" %}

```lua
language = '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-garages/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.