> For the complete documentation index, see [llms.txt](https://mango-5m.gitbook.io/mango5m-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mango-5m.gitbook.io/mango5m-docs/resources/mango-prison/reference/troubleshooting.md).

# Troubleshooting

The common issues and what actually causes them.

<details>

<summary>Players are stuck on a black / never-ending loading screen</summary>

Almost always **illenium-appearance is missing, not started, or erroring**. Mango Prison snapshots a player's appearance at intake and restores it on release through the clothing bridge, and the screen fade only lifts once that completes — so an appearance resource that never responds leaves the screen black.

Check, in order:

1. `ensure illenium-appearance` is in your `server.cfg` and the resource actually started (no red errors in the console at boot).
2. Boot with `Config.Developer = true` and read the bridge line — it prints which clothing adapter was selected (`clothing=illenium`).
3. Not using illenium at all? Set `Config.Clothing = 'skinchanger'` or `Config.Clothing = 'native'` explicitly. The `native` adapter is framework-agnostic and always works (it just doesn't cover tattoos and face overlays).

</details>

<details>

<summary>Corrections officers can't open prison doors</summary>

Mango Prison locks and unlocks doors; **ox\_doorlock decides who may open them**. Each door's JSON needs `"groups": {"doc": 0}` (and/or `"items": ["prison_key"]`) — see [Installation](/mango5m-docs/resources/mango-prison/getting-started/installation.md) for the one-line SQL that applies it to every door, then `restart ox_doorlock`.

Also check the officer actually holds the `doc` job, and that `prison_key` exists in your inventory items if you are relying on the key.

</details>

<details>

<summary>Console warns about door names not found in ox_doorlock</summary>

The names in `config/doors.lua` must match your ox\_doorlock door names **exactly** (they're case-sensitive). The shipped names match the Bolingbroke Interior MLO door pack — if you renamed doors or use a different pack, update the config. Doors that can't be resolved are skipped safely; lockdowns still work for the rest.

</details>

<details>

<summary>Players aren't switched to the prisoner job / released players keep the prisoner job</summary>

Import `sql/jobs.sql` (ESX) or add the `prisoner` and `doc` jobs to your shared jobs (QB/Qbox) — the framework silently refuses to set a job that doesn't exist. Players released while offline get their old job back on their **next login**, not instantly.

</details>

<details>

<summary>The terminal won't open or says ACCESS DENIED</summary>

Your job must be listed in `Config.Guards.jobs` at sufficient grade (QB: you must also be **on duty**), and you must be within `computerMaxDistance` of a terminal from `Config.Locations.computers`. Every action re-checks this server-side — a grade too low for that specific action also reads as denied.

</details>

<details>

<summary>No PA sound plays</summary>

The three built-in tones (`chime`, `alarm`, `buzz`) are synthesized in the NUI — no files needed. For custom audio the file must exist in `html/sounds/` **and** be listed under `files` in `fxmanifest.lua`, then referenced by full filename (`mysound.ogg`).

</details>

<details>

<summary>Prison jobs won't start</summary>

Check the job's start station coordinates (`Config.Locations.stations`), the per-player cooldown, and — if the job has a `timetableZone` — whether the current timetable slot allows that zone. The server also refuses a second concurrent session.

</details>

<details>

<summary>Escapes are impossible / too easy</summary>

The default items are `screwdriver` and `hacksaw` — they must exist in your inventory and realistically reach prisoners (visitor smuggling is the intended route). Tune stage difficulties, alert chances and cooldowns in `config/escape.lua`.

</details>

<details>

<summary>Police never get escape alerts</summary>

`Config.Dispatch` resolved to `none` — no dispatch resource was detected. Set it explicitly to `mango_mdt` / `ps-dispatch`, or wire your own in `bridge/dispatch/custom.lua`. Boot with `Config.Developer = true` to see what the bridge loader picked.

</details>

<details>

<summary>The notification bar sits partway and never moves</summary>

That's mango\_notify's **static accent line**, not a progress bar — it ships with `Config.ProgressBar = false` and draws a short fixed line (`Config.AccentWidth`, 38% wide). Mango Prison sets `Config.NotifyStyle.progress = true` so its own notifications get a real depleting bar; set `Config.ProgressBar = true` in mango\_notify if you want that server-wide.

</details>

<details>

<summary>Police are getting prison PA announcements out in the city</summary>

`Config.Announcements.notifyJobs` is the comms list and defaults to `doc` only — check nothing else was added to it. It's deliberately separate from `Config.Guards.jobs` (terminal access), so police can run the terminal without hearing the PA. Police still receive escapes and riots through the [dispatch bridge](/mango5m-docs/resources/mango-prison/features/police-dispatch.md).

</details>

<details>

<summary>Items went missing on release</summary>

They didn't — nothing is ever deleted (unless contraband mode is `delete`). If the player's inventory was full, the leftovers stay in `mango_prison_property` with `returned = 0` and come back on the next release/restore attempt for that player.

</details>

{% hint style="info" %}
Still stuck? Head to [I Need Support](/mango5m-docs/i-need-support.md) — include your framework, the bridge loader debug line, and any console errors.
{% endhint %}