> 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/free-resources/mango-notify/reference/troubleshooting.md).

# Troubleshooting

Nothing appears, sounds don't play, blank icons, notifications suppressed — matched to what you'll actually see.

<details>

<summary>No notifications appear at all</summary>

1. Confirm the resource is started: `ensure mango_notify` in the server console should not error, and `/mnotify` in game should render the demo set (enable it first with `Config.EnableTestCommand = true` — see Test Command).
2. If `/mnotify` works but your script's calls don't, check the export name — the folder must be `mango_notify` and calls must read `exports.mango_notify:Notify(...)`. A renamed folder breaks every export.
3. If you call notifications **immediately on resource start**, they are not lost — they're buffered until the UI reports ready (about a second after client load) and then play in order. If they never appear, check the F8 console for NUI script errors.

</details>

<details>

<summary>Custom sound doesn't play</summary>

In order of likelihood:

1. The file isn't listed in `fxmanifest.lua` under `files { 'html/sounds/yourfile.mp3' }` — it must be streamed to clients. Add the line and `restart mango_notify`.
2. Name mismatch — `sound = 'alert'` looks for `alert.ogg`, then `alert.mp3`, then `alert.wav` in `html/sounds/`. Check the extension actually matches.
3. The bare name collides with a built-in preset (`notify`, `success`, `error`, `warning`, `dispatch`, `money`) — presets win for bare names. Use the full filename: `sound = 'dispatch.mp3'`.
4. `Config.SoundEnabled = false`, or the call passes `sound = false` / `volume = 0`.

</details>

<details>

<summary>An icon shows as a blank box</summary>

Fonts and icons are bundled, so this is never a connectivity problem. Two causes:

**You used a brand or outline icon.** Only the **solid** Font Awesome family ships. `fa-brands` / `fab` (Twitter, Discord, car makes…) and `fa-regular` / `far` (outline style) have no font file, so they render blank. Use `fa-solid`, which is the default for every built-in type.

To add a family back, download `fa-brands-400.woff2` or `fa-regular-400.woff2` from Font Awesome 6.5.2 into `html/fonts/` and restore its `@font-face` block in `html/css/fontawesome.min.css`.

**The icon name is wrong.** Names change between Font Awesome majors — check it against [the v6 gallery](https://fontawesome.com/search?o=r\&m=free). You can also pass an image path, inline `<svg>`, or a plain emoji instead.

</details>

<details>

<summary>My notification was suppressed / never showed</summary>

Three by-design behaviours to check:

* **Duplicate prevention** — with `Config.DuplicatePrevention = true` (or `dedupe = true`), an identical visible notification is refreshed instead of a new one stacking.
* **Same id** — calling `Notify` with an id that is already on screen updates that notification in place rather than adding a second one.
* **Queue** — when `Config.MaxNotifications` are already visible, new notifications wait for a slot (in `'queue'` mode). Send with `priority = 10` to jump ahead, or use `queueMode = 'replace'`.

</details>

<details>

<summary>Update(id, ...) does nothing</summary>

`Update` only affects a notification that is currently visible or queued. If it already expired or was removed, the call is a no-op by design — send a fresh `Notify` with the same id instead (which also updates in place when it *is* still visible, so this pattern is safe either way).

</details>

<details>

<summary>Progress bar doesn't show</summary>

`progress = true` needs a real duration — a persistent notification (`duration = 0`) shows the static accent line instead, since there is no countdown to display. Give it a duration, or drive progress manually by updating the description text.

</details>

<details>

<summary>ox_lib notifications still look like ox_lib</summary>

The one-line redirect in `ox_lib/resource/interface/client/notify.lua` either wasn't applied or isn't live yet:

1. Check you replaced the `SendNUIMessage({ action = 'notify', data = payload })` block with `exports.mango_notify:OxNotify(payload)` — inside `lib.notify`, not `lib.defaultNotify`.
2. `restart ox_lib` afterwards. Restarting mango\_notify alone won't reload ox\_lib's code.
3. An ox\_lib update overwrites the file — re-apply the line after every update.
4. Seeing **two** notifications for one call means ox\_lib's `SendNUIMessage` is still there alongside the new line. Replace it rather than adding to it.

See Framework Integration.

</details>

<details>

<summary>Console says "playerId is nil" and nothing shows</summary>

A server export was called without a valid player id. The most common cause is reading `source` somewhere it is not set — inside a timer, a callback, or a function called from another resource.

```lua
-- source is nil here, so nothing is sent
CreateThread(function()
    exports.mango_notify:Success(source, 'Done')
end)

-- capture it first
local player = source
CreateThread(function()
    exports.mango_notify:Success(player, 'Done')
end)
```

Mango Notify refuses `nil` rather than falling back to `-1`, which would notify every player on the server. If you did mean everyone, call `NotifyAll(data)`.

A `player N is not connected` warning means the same call arrived after that player dropped — usually harmless.

</details>

{% hint style="info" %}
Still stuck? Head to I Need Support — include your server artifact version, what you called (the exact export/event and data), and any F8 console errors.
{% endhint %}