# Troubleshooting

## The chat does not show or stays empty

The resource needs the built UI in `web/build`. A source download of the repository does not include it. Use the release ZIP, or build it, see [Installation](/new/chat/installation).

## Two chats, or the old chat still answers

The default `chat` resource is still running. Remove `ensure chat` and make sure nothing else starts it (`[system]` starts it by default). Koja Chat replaces it with `provide 'chat'`. Start `koja-chat` after `koja-lib`.

## The chat does not open when I press T

- Another resource has the NUI focus, or the pause menu is open. The chat does not open then.
- `CustomClient.CanOpen` in `editable/client.lua` returns `false` (for example while handcuffed or dead).
- A script called `SetHidden(true)` and never turned it off.
- The player rebound the key in GTA settings, Key Bindings, FiveM. `Config.OpenKey` is only the default.

## A player does not see the Local messages of someone nearby

Local uses `range = 20.0` metres by default, and `/w` only 3 m. Proximity is calculated on the server with OneSync. Without OneSync the clients filter by distance, which only works for players in scope. Players in different routing buckets do not see each other.

## A tab is missing

- The channel is `hidden`, or has `admin`, `jobs` or `department` that the player does not match.
- The department tab only appears when the job is listed in `Config.Departments`. With `Config.DepartmentsRequireDuty = true` the player must be on duty.
- A custom `canSee` depends on something that changed. Call `Refresh(src)` after it changes.

## Staff do not get the Staff tab or admin commands

Staff come from `Custom.IsAdmin`. Check `Config.AdminGroups` and `Config.AdminAce`, or the koja-lib `Config.Admin` when both are `nil`.

## The Console tab does not show up

- `Config.DevMode.enabled` must be `true`.
- The player needs the ACE from `Config.DevMode.ace`: `add_ace group.admin koja-chat.dev allow`.
- If the console prints `RegisterConsoleListener is not available on this server build`, update the server build. The tab then only shows the commands you run.
- Typing a command does nothing unless `Config.DevMode.execute = true`.

## A link does not show an image

Only links from the hosts in `Config.Images.hosts` get a preview, and only when `Config.Images.enabled` is `true`. Add the host to the list.

## Pasting an image does not work

- `Config.Images.paste.enabled` must be `true`.
- The image is rejected when it is bigger than `paste.maxKB` after compression. The player sees "The image is too big."
- Players can send one image per `paste.cooldown` seconds. Staff are not limited.

## A player is muted and does not know why

Mutes are stored by license in the resource KVP and survive reconnects and restarts. `IsMuted(source)` returns the reason, who muted and the seconds left. `/unmute <id>` removes it. Spam can also mute automatically, see `Config.AntiSpam.autoMute`.

## "Slow down, you are typing too fast."

The anti-spam is blocking messages: more than `burst` messages in `window` seconds, or less than `interval` ms between two. Staff are not affected. Raise the values or set `Config.AntiSpam.enabled = false`. Slow mode set with `/slowmode` stays active either way.

## Speech bubbles do not show

- `Config.Bubbles.enabled` must be `true`. When it is `false`, `/me`, `/do` and `/try` use the 3D text of `Config.OverheadText` instead.
- Only `Config.Bubbles.max` bubbles are drawn at once, and only within `distance`.
- Plain messages get a bubble only on the channels listed in `Config.Bubbles.channels`.

## A command from my script says "Unknown command"

The command is not registered with `RegisterCommand`. Koja Chat fires `chatMessage` for unknown commands first. If a script cancels that event with `CancelEvent()`, no error is shown.

## A hook throws an error

```
[koja-chat] beforeSend hook from my-resource failed: ...
```

The error is in the named resource. The message continues as if the hook returned nothing.

## /bind says the key is invalid

Use letters, numbers and underscores, up to 16 characters, for example `F5`, `NUMPAD1` or `X`. The limit per player is `Config.Binds.max`.