> For the complete documentation index, see [llms.txt](https://hane-mod-studio.gitbook.io/hane-mod-studio/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://hane-mod-studio.gitbook.io/hane-mod-studio/hane-scripts/hane-gps/faq-and-troubleshooting.md).

# FAQ & Troubleshooting

Common Issues

#### GPS item doesn't work

* Make sure the item name in your inventory matches `Config.Item` (default: `'gps_device'`).
* For **ox\_inventory**, verify the item has the correct `client.export`:

  ```lua
  client = {
      export = 'hane_gps.useGPS'
  }
  ```
* For **qb-inventory / qs-inventory**, ensure you have registered the useable item callback.
* Check that `Config.Inventory` is set correctly or use `'auto'`.

#### Can't see other players on the GPS

* Both players must be **on-duty** in the **same job**.
* Both players must have the GPS **activated** (toggled on via the NUI).
* Check that the job is listed in `Config.Jobs` with `enabled = true`.
* Verify `Config.RefreshInterval` is not set too high.

#### Blips disappear or flicker

* This can happen when entity-based blips lose their target (player goes out of range).
* The system automatically falls back to coordinate blips in this case.
* If blips are updating too slowly, lower `Config.RefreshInterval`.

#### Callsigns not showing

* Callsigns require **lb-tablet** to be installed and running.
* Check `Config.CallsignJobType` mapping for the relevant job.
* If lb-tablet is not installed, the system falls back to the job `label` from config.

#### Unit names not showing

* Unit names require **hane\_dispatch** to be installed and running.
* The player must be assigned to a unit in the dispatch system.

#### GPS doesn't close on job change

* The GPS automatically deactivates and clears blips when:
  * The player changes job
  * The player toggles off-duty
  * The player disconnects
* If this isn't working, check that your framework properly fires job update events.

***

### Performance

* The server refresh loop runs at `Config.RefreshInterval` intervals (default: 5 seconds).
* Only active GPS users have their positions cached and broadcast.
* Blips are only sent to players in the same job, minimizing network traffic.
* Entity-based blips are preferred for smooth client-side tracking.

***

### Support

For installation, setup, and usage-related questions, join our Discord server.