FernandoJVideiraandClaude Sonnet 5.5
02b7db1813
- README, license section and architecture no longer point to the dashboard repositories - schema.sql is the schema for contributors; database changes only need schema.sql and a note in the PR - self-hosting: settings without a dashboard (SQL for security thresholds, beta settings, opted-in servers) - beta features, deployment and troubleshooting reworded for people who don't have the dashboard Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
58 lines
4.0 KiB
Markdown
58 lines
4.0 KiB
Markdown
# 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.
|