Troubleshooting PolarBot

Start with these two commands; almost every problem shows up in them:

systemctl status polarbot --no-pager
sudo journalctl -u polarbot -n 50 --no-pager

For more detail, set [log] level = "polarbot=debug,info" in /etc/polarbot/config.toml, restart, reproduce the problem, and set it back to "info".

The service does not run

`status=78/CONFIG` and it is not restarted

Exit status 78 means Discord refused the connection for a reason a restart cannot fix, so systemd stops restarting it (RestartPreventExitStatus=78). The log’s last error says which:

Discord refused the gateway intents (close code 4014): the privileged intents are not enabled. In the Developer Portal, your application, Bot → Privileged Gateway Intents: enable Presence Intent, Server Members Intent and Message Content Intent, and save.
fatal close code 4004: the token is wrong or was reset. Store the current one again (Configure → Credentials).
Another fatal close code: see Discord’s list of gateway close codes.

Then:

sudo systemctl reset-failed polarbot
sudo systemctl start polarbot

`status=1/FAILURE`

The bot started and stopped with an error; the log’s last lines say why:

Log says	Fix
`invalid config: line N: …`	A typo or unknown key in `/etc/polarbot/config.toml`; see Configuration file.
`secret-looking key … found in config`	Remove the secret from the config file; secrets are credentials.
`secret … discord_token … is missing`	The credential is not loaded: check that `/etc/polarbot/discord_token.cred` exists and the unit has its `LoadCredentialEncrypted=` line.
An HTTP `401` (Unauthorized) error right after `starting polarbot`	The token is wrong or was reset; store it again.
`migration … was previously applied but is missing` (or similar)	The binary is older than the database; see Roll back.
`discord.dev_guild_id must not be 0`	Remove or fix `dev_guild_id`.

After 5 failed starts within 10 minutes systemd gives up (start-limit-hit); after fixing the cause run sudo systemctl reset-failed polarbot and start it.

systemd could not decrypt a credential before starting the bot: a .cred file named in the unit is missing, or it was made on another machine (credentials are tied to the machine’s key). Create it again (Install, step 7 and OAuth, step 6), or remove the LoadCredentialEncrypted= lines for the OAuth credentials if you do not use command visibility.

The bot is online but …

… the slash commands do not appear

Global commands can take a few minutes to show up the first time. Restart Discord (Ctrl+R).
The log must contain registered global commands. If it says command registration failed, the reason follows.
The bot was invited without the applications.commands scope: invite it again with the link from Install, step 1.
Staff commands are only shown to Administrators until an Owner runs /perms authorize.
With dev_guild_id set, commands exist only in that one server.

… a command says I may not use it

PolarBot checks its own levels, not Discord’s. /perms list shows which roles have which level; members with Administrator and the server owner are always Owner. Commands lists the level of every command.

… moderation fails with “missing permissions” or a hierarchy message

The bot needs the permissions from the invite link (Kick, Ban, Timeout Members, Manage Messages, …). Check the bot’s role in Server Settings → Roles, and channel overrides that deny it.
Discord never lets a bot act on the server owner, or on members whose highest role is at or above the bot’s highest role: move PolarBot’s role higher.
You can only act on members below you, in Discord’s role order and in PolarBot’s levels.

… nothing appears in the log channel

/config view shows the log channel and level. Level 0 posts nothing; scanner cards need level 1 or higher.
The bot needs View Channel, Send Messages and Embed Links in the log channel (/setup checks this when you choose it; channel overrides changed later can break it).
If the log channel was deleted, PolarBot cleared the setting: run /setup again.

… the scanner does not delete or punish

/scanner status says whether log-only mode is on (/scanner actions enabled:True turns actions on).
Moderators and above, exempt roles and exempt or unmonitored channels are never scanned.
/scanner analyze shows the score and what the scanner would do with a given text or message.
A card that says the action failed shows why (usually permissions or role order, above).

… the threat lists stay empty

The log says list download failed; keeping the previous list with the reason. The server needs outbound HTTPS to the list URLs (by default raw.githubusercontent.com). Until the first download succeeds, threat-list matches cannot happen (all other rules work).

Command visibility (OAuth)

Symptom	Cause and fix
`/perms authorize` says visibility sync is not set up	The OAuth credentials are not loaded. Set them up (OAuth and nginx); the log says `OAuth credentials not configured` or `OAuth credentials invalid` (`oauth_key` must be 64 hex characters).
Discord shows “Invalid OAuth2 redirect_uri”	The redirect in the Developer Portal must be exactly `<public_url>/oauth/callback`, with the `public_url` from the config file (no trailing slash, `https`).
The page says the link is invalid or expired	Links work once and for 10 minutes. Run `/perms authorize` again.
`502 Bad Gateway` from nginx	The bot’s web server is not running: check the log for `web server listening` (it only starts with both OAuth credentials) and `curl http://127.0.0.1:8787/healthz` on the server. On Fedora, also `sudo setsebool -P httpd_can_network_connect 1`.
The certificate request fails	DNS must point at the server, port 80 must be reachable, and a proxying DNS provider must be set to DNS only for the first request.
Roles still see the wrong commands	The sync runs a few seconds after each `/perms` change; the log says `command visibility synced` or why it failed. If the authorizing admin lost their rights or revoked the app, `/perms` asks for `/perms authorize` again.

Still stuck?

Open an issue at https://github.com/sergeantpolarbear/PolarSystems/issues with the output of the two commands at the top of this page (check it for anything private first; it never contains tokens), or write to contact@polarsystems.net.

PolarSystems documentation