> For the complete documentation index, see [llms.txt](https://docs.sonoransoftware.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sonoransoftware.com/store/sonoran-station-displays/troubleshooting.md).

# Troubleshooting

## Resource does not start

**Likely cause:** Incorrect folder nesting, missing manifest files, Lua error, or an incomplete escrow download.

**Verify:**

* `fxmanifest.lua` is directly inside `resources/.../sonoran-stationdisplay/`.
* The server console identifies the first file/error.
* `web/index.html`, `web/style.css`, `web/app.js`, and `data/displays.DEFAULT.json` exist.

**Corrective action:** Re-extract the package, remove any duplicate outer folder, and restore the complete resource. Do not combine files from different versions.

**Relevant logs:** FXServer startup errors before the normal `[Sonoran Station Displays]` messages.

## SonoranCADFiveM is not detected

**Likely cause:** Wrong resource name, wrong start order, version below `4.0.72`, or missing cache exports.

**Verify:**

```cfg
ensure sonorancad
ensure sonoran-stationdisplay
```

Run from the server console:

```
stationdisplay_serverdiag
```

**Corrective action:** Install or update SonoranCADFiveM to version `4.0.72` or newer, keep its resource name `sonorancad`, and start it before Station Displays.

**Relevant logs:**

| Code          | Meaning                                |
| ------------- | -------------------------------------- |
| `SSD-CAD-001` | Configured CAD resource is not started |
| `SSD-CAD-002` | Required cache exports are unavailable |
| `SSD-CAD-003` | Version is below the supported minimum |

## Version checker does not run

**Likely cause:** The resource is a source or development build rather than an official packaged release.

**Verify:** Confirm the resource was downloaded from the official granted asset.

**Corrective action:** Install the official packaged release. Development builds intentionally retain the packaging token and skip outbound version requests.

## Update check fails

**Likely cause:** FXServer cannot reach the packaged version endpoint, the request timed out, or the endpoint returned malformed metadata.

**Verify:** Review `SSD-UPDATE-001` or `SSD-UPDATE-002` in the server console and confirm outbound HTTPS access.

**Corrective action:** Restore outbound HTTP access and retry at the next scheduled check or resource start. An update-check failure does not stop the display resource.

## SonoranCAD version is unsupported

**Likely cause:** The installed `sonorancad` version is older than `4.0.72`.

**Corrective action:** Update SonoranCADFiveM to version `4.0.72` or newer so the public unit, call, and emergency cache interfaces are available.

## Customer config contains removed settings

**Likely cause:** An older `config.lua` was copied over the current package.

**Corrective action:** Delete obsolete update-check, dependency, DUI resolution/lifecycle, and event-rate-limit entries, then merge only documented customer-facing settings into the current config. Do not modify protected implementation files; internal values always take precedence.

## Display is blank

**Likely cause:** Outside render distance, DUI pool full, invalid/unloaded model, incorrect custom surface geometry, missing web files, or a client script error.

**Verify:**

* Walk close to the display.
* Open diagnostics and check **Active DUIs**.
* Compare with `Config.MaximumActiveDuis`.
* Check the client F8 console.
* Confirm the model exists in `Config.DisplayModels`.

**Corrective action:** Use **Force-Refresh Display**, leave/re-enter range, reduce overlapping render distances, restore web files, or correct the model registry. For identical props, use `WORLD_PLANE`.

**Relevant logs:** Client F8 errors for DUI creation, NUI JavaScript, model loading, or render targets.

## Display shows no units

**Likely cause:** No matching on-duty cache entries, offline status, wrong service filter, or **Hide Unavailable Units**.

**Verify:**

```
sonorancad viewcaches
```

Confirm the unit is in the active unit cache and inspect `data.page` and status.

**Corrective action:** Put the unit on duty in CAD, select the correct LEO/Fire/EMS/Both filter, or disable **Hide Unavailable Units**.

**Relevant diagnostics:** LEO Units, Fire/EMS Units, CAD Compatible, cache revision.

## LEO or Fire/EMS unit is in the wrong section

**Likely cause:** Incorrect `unit.data.page` in the CAD cache.

**Verify:**

* `0` should be LEO.
* `1` and `2` should be Fire/EMS.
* `3` and unknown values become `OTHER`.

**Corrective action:** Fix the upstream cache classification. Use advanced service overrides only for a confirmed custom/legacy cache.

**Relevant logs:** Debug output and `sonorancad viewcaches`; no department list is normally required.

## Calls do not appear

**Likely cause:** Wrong page/cache, closed dispatch call, service mismatch, unclassified call hidden on a single-service display, or unavailable call cache.

**Verify:**

* Emergency Calls reads `GetEmergencyCache()`.
* Dispatch Calls reads `GetCallCache()`.
* Check assignments and call status.
* Compare emergency/dispatch counts in diagnostics.

**Corrective action:** Select the correct page, keep the call active in the source cache, assign a classified unit, use a Both display, or intentionally enable the unclassified fallback.

**Relevant diagnostics:** Emergency Calls, Dispatch Calls, CAD error, cache revision.

## Live Map is empty

**Likely cause:** Matching units/calls have no usable X/Y coordinates, markers are filtered, or the fixed region excludes them.

**Verify:**

* Confirm list pages contain records.
* Inspect CAD coordinate fields.
* Check map mode, center, zoom, **Show Calls**, and the service filter.

**Corrective action:** Restore upstream coordinates, use Auto Fit, correct the fixed center/zoom, or enable the required markers.

**Relevant logs:** Temporarily enable `Config.Map.debug` to inspect calibrated bounds, asset crop, clipping, and selected viewport values. Disable it afterward.

## Live Map markers are misaligned

**Likely cause:** A coordinate source uses another map convention, the record is outside the calibrated GTA V bounds, or custom browser/map files were mixed between versions.

**Verify:** Restore the shipped `gtav-satellite-z4.webp` and `map-config.js`, enable the map debug overlay, and compare a known landmark.

**Corrective action:** Replace the complete `web/` directory from one release and fix the upstream world coordinates. Do not tune bounds to compensate for one malformed record.

## Bodycams do not appear

**Likely cause:** The installed CAD package lacks the bodycam state bridge, `screenshot-basic` is not started, the bodycam is disabled/off duty, or the display filter/page excludes it.

**Verify:** Open [Diagnostics](/store/sonoran-station-displays/diagnostics.md) and check bodycam detected, available, mode, active sources, capture dependency, and subscription counts.

**Corrective action:** Install a compatible SonoranCADFiveM bodycam package, start `screenshot-basic`, put the unit on duty, activate the bodycam, and enable the `BODYCAMS` page.

## Bodycam stays connecting or unavailable

**Likely cause:** The officer is loading/paused/faded, local capture failed, the JPEG exceeded 300 KB, or the viewer subscription is out of range/ineligible.

**Verify:** Review last attempt/success, upload duration, frame size, failure reason, source client, subscriber count, and malformed/oversized counters.

**Corrective action:** Restore `screenshot-basic`, let the officer finish loading, reduce game resolution if frames exceed the limit, and verify range, routing bucket, interior, current bodycam page, and service filter.

## Display is visible but frozen

**Likely cause:** CAD cache stopped changing, connection is unavailable, DUI state is not being resent, or the browser encountered an error.

**Verify:**

* Check `CAD LIVE` versus the disconnected overlay.
* Refresh diagnostics and watch cache revision.
* Run `stationdisplay_serverdiag`.
* Check client F8.

**Corrective action:** Restore SonoranCADFiveM, use **Force-Refresh Display**, then leave/re-enter range. Restart `sonoran-stationdisplay` only after preserving persistence if the client state remains unhealthy.

**Relevant data:** Cache revision and the server diagnostic CAD object. The menu does not show per-DUI last-update timestamps.

## Menu does not open

**Likely cause:** Missing `sonoran.stationdisplay.menu`, changed command name, placement already active, or a client error.

**Verify:**

* Check `Config.AdminCommand`.
* Test the configured command.
* Check ACE inheritance with the server's ACE tools/config.
* Check client F8.

**Corrective action:** Grant `sonoran.stationdisplay.menu`, finish/cancel placement, or fix the reported client error.

**Relevant logs:** Permission-denied notification and F8 errors. No radio resource is required.

## Menu opens but an option reports no permission

**Likely cause:** The server-provided menu snapshot is older than the player's current ACE state, the operation uses a different node, or a server recheck correctly rejected the action.

**Verify:** Compare the requested action with [Permissions](/store/sonoran-station-displays/permissions.md), then run `stationdisplay_permissiondiag <serverId>` from the console while `Config.Debug = true`.

**Corrective action:** Grant the exact node, review inherited deny rules, and reconnect or refresh the menu snapshot. Do not treat a visible item as authorization.

**Relevant permission:** Menu, place, edit, refresh, delete, diagnostics, and webhook test are independent server checks.

## Cannot place or edit a display

**Likely cause:** Missing `place`/`edit`, final position farther than 15 meters, invalid value, routing-bucket mismatch, or event rate limit.

**Verify:**

* Confirm the exact ACE.
* Stay near the position.
* Keep numeric values in documented ranges.
* Review the on-screen rejection notification.

**Corrective action:** Grant the needed ACE, move closer, restore valid settings, or wait for the 10-second rate window.

**Relevant logs:** Client notification such as permission denied, invalid request, position, or bucket mismatch.

## Display saves but does not update live

**Likely cause:** Persistence succeeded but the client broadcast failed, the viewer lost connectivity or world scope, or its DUI is unavailable.

**Verify:** Look for `CLIENT_BROADCAST_FAILED`, compare the persistence audit ID, run `stationdisplay_serverdiag`, and inspect Active DUIs/client F8.

**Corrective action:** Restore client connectivity and world scope, use **Force-Refresh Display**, or run **Full Display Resync** with diagnostics permission. Do not replace a valid persistence file for a broadcast-only failure.

## Default JSON is not initialized

**Likely cause:** The shipped default is missing/invalid, the resource cannot write its data directory, or an invalid active file already exists and was intentionally preserved.

**Verify:** Check `data/displays.DEFAULT.json`, `data/displays.json`, and `SSD-PERSIST-INIT-*`; `SSD-PERSIST-INIT-005` means the existing active file was not overwritten.

**Corrective action:** Stop the resource, preserve the active file, restore a valid default from the package, fix filesystem access, then restart. Use the console repair command only when recovery from the active file is not possible.

## DUI readiness times out

**Likely cause:** A missing/mixed `web/` directory, browser JavaScript failure, or a client DUI/runtime-texture problem prevented `duiReady` within 10 seconds.

**Verify:** Inspect client F8 and confirm all production web files come from the same resource release.

**Corrective action:** Restore the complete `web/` directory, leave/re-enter range, and let the internal one-second retry run. Repeated timeouts require client/runtime investigation rather than increasing an internal timeout.

## Display disappears at a distance

**Likely cause:** Normal distance-based cleanup.

**Verify:** Compare distance with the display's saved render distance. The object should disappear after the 3-second default destroy delay.

**Corrective action:** Increase the per-display render distance only as much as needed. Maximum accepted value is 250 meters.

**Relevant diagnostics:** Active DUI count should decrease after cleanup.

## Custom television stays black or shares content

**Likely cause:** Invalid named render target, global texture replacement, missing model, or incorrect world-plane offsets.

**Verify:**

* Switch the model entry to `WORLD_PLANE`.
* Test one instance and then two identical instances with different pages.
* Confirm model validity and local screen geometry.

**Corrective action:** Calibrate `screen.center`, `width`, `height`, and `flipX`. Do not rely on a render-target name alone.

**Relevant logs:** Client model/render errors; diagnostics only reports active DUI availability, not named-target validity.

## Settings reset after restart

**Likely cause:** `data/displays.json` cannot be loaded, one entry failed validation, or the resource folder was replaced without restoring runtime data.

**Verify:** Check the file and startup log's loaded display count.

**Corrective action:** Stop the resource, restore a valid backup, confirm write permission, and restart.

**Relevant logs:** `SSD-PERSIST-001`, `SSD-PERSIST-002`, or `SSD-PERSIST-003`.

## Page rotation is not working

**Likely cause:** One page enabled, rotation disabled, invalid interval reset to default, or a recent viewer interaction is inside the default 10-second hold.

**Verify:**

* Confirm two or more enabled pages.
* Confirm **Page Rotation** is enabled.
* Confirm interval is 5–300 seconds.
* Watch the footer dots/progress bar.

**Corrective action:** Enable multiple pages, save rotation, use a valid interval, wait for the interaction hold, and force refresh if needed. A recreated DUI restores the server runtime snapshot rather than always starting from the saved default.

**Relevant logs:** No dedicated rotation log. Use the displayed footer and current page.

## Nearby page prompt does not appear

**Likely cause:** No applicable action, outside the display's saved interaction distance, poor view angle, failed line of sight, wrong interior/bucket, unavailable DUI, or disabled page interaction.

**Verify:** Stand within 2.5 meters by default, face the screen, and test a display with multiple pages or Live Map/Bodycams controls.

**Corrective action:** Correct the display's interaction distance and world context, enable `Config.PageInteraction`, and remove geometry blocking line of sight. A one-page display intentionally hides the prompt only when its current page has no map/bodycam action.

## The wrong nearby display changes page

**Likely cause:** Another display has the better combined distance/view-angle target score even if it is not the closest object.

**Verify:** Face the intended screen directly and move closer while watching the prompt name.

**Corrective action:** Separate overlapping displays, shorten their interaction distances, or approach the intended surface from a clearer angle. The server still checks proximity and world context before broadcasting the change.

## Rotation resumes too soon after manual interaction

**Likely cause:** `PageInteraction.pauseRotationAfterInteraction` is low/zero, the configuration was not restarted, or an integration forced another runtime page.

**Verify:** Confirm the default 10-second value and compare the timing with server `SetDisplayPage` calls.

**Corrective action:** Restore the desired hold value and restart the resource. The manual page change itself is runtime-only and does not change the saved default.

## Live Map is clipped or letterboxed

**Likely cause:** Normal aspect-ratio containment, a custom/mixed map asset, or an incorrect model surface ratio.

**Verify:** The shipped map intentionally uses the actual contained image rectangle; side bands can appear on a 16:9 viewport. Enable map debug and confirm markers align inside the displayed image.

**Corrective action:** Restore the shipped asset/config and calibrate the model surface to 16:9. Do not project markers across the letterboxed bands.

## Bodycam feed is delayed or fails to load

**Likely cause:** Local capture or decode failed, the frame was oversized, the officer paused/loaded/disconnected, or the subscription expired.

**Verify:** Watch `DELAYED` versus `CAPTURE FAILED`/`OFFLINE`, check client logs, and inspect capture timing, frame size, subscriber, malformed, oversized, and stale counters.

**Corrective action:** Restore local capture readiness, reduce feed count, and re-enter render range. The last frame remains briefly and is removed after 30 seconds.

## Administrative webhook does not arrive

**Likely cause:** Disabled/malformed private URL, Discord 4xx, outbound HTTPS failure, rate/test cooldown, or a queue retry in progress.

**Verify:** Run the in-menu webhook test with `sonoran.stationdisplay.webhook.test`, retain its audit ID, and inspect the server response log.

**Corrective action:** Regenerate invalid credentials, restore outbound HTTPS, and allow 429/5xx retries. The administrative action can still succeed because delivery is non-blocking.

## High client resource usage

**Likely cause:** Too many nearby DUIs, long render distances, raised DUI resolution, high row limits, or many map markers.

**Verify:** Open diagnostics and compare Nearby Displays, Active DUIs, and `MaximumActiveDuis`.

**Corrective action:** Reduce render distances, nearby display count, resolution, row limits, or call markers. Keep no more than eight active DUIs with default limits.

**Relevant data:** Client profiler/F8 plus menu DUI counts.

## Diagnostics

See [Diagnostics](/store/sonoran-station-displays/diagnostics.md) for the in-game snapshot, server/permission commands, persistence repair, map overlay, full resync, and bodycam counters.

## Error and warning codes

| Code              | Meaning                                                                      |
| ----------------- | ---------------------------------------------------------------------------- |
| `SSD-CAD-001`     | Configured SonoranCADFiveM resource is not started                           |
| `SSD-CAD-002`     | Required CAD cache exports are missing                                       |
| `SSD-CAD-003`     | CAD version is below the supported minimum                                   |
| `SSD-PERSIST-001` | Persistence JSON is malformed                                                |
| `SSD-PERSIST-002` | One saved display failed validation                                          |
| `SSD-PERSIST-003` | Encode/write/readback/validation/exact-state persistence verification failed |
| `SSD-UPDATE-001`  | Remote version request failed                                                |
| `SSD-UPDATE-002`  | Remote version payload is invalid                                            |
| `SSD-UPDATE-003`  | A newer resource version is available                                        |

## Support checklist

Before contacting [Sonoran Support](https://support.sonoransoftware.com/), collect:

* Sonoran Station Displays version
* SonoranCADFiveM version
* FXServer artifact version
* Relevant `config.lua` sections with secrets and identifiers removed
* Server console errors and `stationdisplay_serverdiag` output
* Client F8 errors
* In-game diagnostic values
* Display ID/name
* Display model and configured render method/target
* Current service filter and page
* Exact reproduction steps

Never post CAD API keys, Tebex credentials, license credentials, private caller data, or unredacted player identifiers.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.sonoransoftware.com/store/sonoran-station-displays/troubleshooting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.