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.

Dashboard actions have no effect

The dashboard talks to the bot through the database (see Database).

• Check that the bot and the API 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 chosen on the dashboard? 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 has its owner switched on Beta features on the dashboard? 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.