# Troubleshooting

## The bot does not start

| Message | Cause |
| --- | --- |
| `BOT_TOKEN is not set`, `APP_ID is not set`, `DB_HOST is not set` | A required variable is missing. See [Getting started](getting-started.md#2-configure-the-environment). |
| `TWITCH_CLIENT_ID is not set` | It is required even if you do not use Twitch alerts. Set any non-empty value. |
| `Error creating database` | `DB_HOST` is wrong, or PostgreSQL is not running or not reachable. Try the connection string with `psql`. |
| `Error starting bot` | The token is wrong, or a privileged intent is not enabled in the developer portal. |
| `Disallowed intents` | Enable **Server Members Intent** and **Message Content Intent** in the developer portal, under Bot. |

## Slash commands do not appear

- With `GUILD_ID` set, commands appear in that server within seconds. If it is empty they are global and can take up to an hour.
- The bot must be invited with the `applications.commands` scope.
- If a command is defined but not in the `handlers` map in `internal/commands/commands.go`, it shows up and does nothing.
- If the bot logs `Cannot create '<name>' command`, read the error. A name or description that is too long, or an invalid option, makes Discord reject that one command.
- Commands that you removed from the code stay in Discord until you delete them (in the developer portal or through the API).

## A command says "You don't have permission"

Many commands need **Manage Server** (see the [Command reference](commands.md)), and the music commands need a role called exactly **DJ**. Security actions such as turning protection off need the **server owner or a trusted user**, whatever permissions you have.

## The bot cannot do something in a server

Most failures are about the bot's role:

- The bot's role must be **above** the roles it manages and the members it moderates or quarantines.
- It needs the permissions listed in [Getting started](getting-started.md#1-create-the-discord-application). Check the channel's own permission overrides too: a channel can deny what the server role allows.
- Security messages say "Check that Velox's role is high enough and has the permissions it needs" for this reason.

## Music does not play

- `LAVALINK_HOST` and `LAVALINK_PASSWORD` must match your Lavalink server, and Lavalink must be running and reachable from the bot (in Compose, use the service name, not `localhost`).
- You need the **DJ** role.
- A server admin can turn music off with `/music toggle`.

## Level-ups, logs or welcome messages do nothing

They are off until enabled: `/slvl toggle`, `/config enablelogging` with `/config setlogchannel`, and `/config setwelcomechannel`. Leveling and spam detection read message text, so the **Message Content Intent** must be on. Welcome messages and security need the **Server Members Intent**.

## A dashboard or tool's requests have no effect

A dashboard (the hosted Velox has a proprietary one) or any tool of yours talks to the bot through the database (see [Database](database.md#dashboard-to-bot-settings-and-requests)).

- Check that the tool and the bot use the **same database**.
- For a request such as skipping a song or ending a raid, look in the matching `*_commands` table. A row with an empty `processed_at` is waiting. If many are waiting, the bot's listener is down: look for `command listener stopped` in its log. It reconnects every 10 seconds.
- Settings are read when needed and may be cached briefly (the beta settings are polled every 30 seconds).

## Beta features are not available to a tester

Go through [Beta features](beta-features.md): is the Beta Tester role set in `beta_settings`? Is the person in the **beta server**, and do they have the role there? Is the server where they use it the beta server, or is it listed in `beta_guilds`? Has 30 seconds passed? `/beta` (owner only) shows how access is set up.

## Getting more detail

The bot logs to standard output. Run `docker compose logs -f bot`, or just `go run .`, and reproduce the problem. Errors from Discord calls are logged with the server and channel IDs involved.