velox-bot/docs/troubleshooting.md

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.
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), 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. 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).

• 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: 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.