Troubleshooting

Troubleshooting

Configuration errors

The bot checks config.toml at start. When a setting is wrong, it prints the problem and stops. For example:

DISCORD_TOKEN is not set
/config/config.toml: unknown setting 'intervall'; did you mean 'interval'?
/config/config.toml: missing required setting(s) ['guild_id']
/config/config.toml: missing required setting(s) ['outputs']
/config/config.toml: [[outputs]] entry 1.channel: expected integer; Discord channel id.
['shown'] sit under [tasks.rename]; move them above it, into [tasks]

A setting that sits under a table header belongs to that table. Put the plain keys of a table above its sub-tables (see Configuration).

A problem with config_format stops the bot. The log shows the path of config.toml, then the error:

Error	Fix
configuration requires a bounded positive integer format	Add config_format = 1 at the top of config.toml.
configuration format is unsupported; run setup.sh --action migrate	Run the install line from Installation with --action migrate added at the end.
configuration was written by a newer Shazzzbot	Upgrade the bot, or use a config.toml for this version.

The container restarts on its own, so the same error repeats in the log until you correct the file. After each change to config.toml, recreate the bot container:

docker compose up -d --force-recreate shazzzbot

Logs

For a Compose install, run these commands in the install directory on the server:

docker compose ps
docker compose logs -f shazzzbot
docker compose logs docker-proxy

For the log of the host helper, see Host helper.

To get more detail for a bug report:

1. In config.toml, set log_level = "debug".
2. Restart the bot. For a Compose install, run docker compose restart shazzzbot in the install directory. For a docker-run or bot-only install, run docker restart shazzzbot.
3. Make the problem occur again.
4. Save the log at once. For a Compose install, run docker compose logs --since 1h shazzzbot > shazzzbot.log. For a docker-run or bot-only install, run docker logs --since 1h shazzzbot > shazzzbot.log 2>&1.

Note

Docker keeps about 30 MB of log for each container and then deletes the oldest lines. Debug lines fill that space faster, so save the log soon after the problem occurs. Debug turns itself off after debug_hours (24 by default).

Before you share a log, remove tokens, keys, Discord ids, host names, and IP addresses from it.

Symptom	Cause
Docker Compose says required variable SHAZZZBOT_INSTALL_ID is missing a value, or the same for HELPER_SOCKET_DIR	.env does not set that variable. Run setup.sh, or see Installation.
panel channel 123456789012345678 not found in the log	The channel id of an output is wrong, or the bot cannot see the channel.
No slash commands in Discord	The invite did not include the applications.commands scope. Invite the bot again.
A command gets no reply	The command was used outside the output channels and commands_channel_id.
Not allowed.	Your role or user id is not in a tier that allows the command.
The audit channel is not set or not reachable, so changes are turned off.	Set audit_channel_id, and give the bot View Channels and Send Messages in that channel.
`name` is not in restarts.allow.	Add a pattern for the container to [restarts] allow (see Restarts).
Docker is not configured.	Set [host] docker_proxy.
Blowup is not configured.	Set blowup_user_id.
needs the shazzzbot helper in the Tasks section	The [helper] table is not set, or the bot cannot get data from the helper. Without a [helper] table, this row is normal.
helper is unavailable or its tasks could not be read in the log	The helper does not run, the key in .env does not agree with api.key, or tasks is not in enabled. Read the helper log.
helper failed: ValueError from the helper	A check of the helper failed (see Configuration check).
Every service shows missing	[host] docker_proxy is not set, or the bot cannot reach the proxy.
403 lines in the docker-proxy log	The proxy refused a request that is not on its allowlist.

If you delete a status message, the bot posts a new one at the next update.