Troubleshooting

The bot starts then exits with a migrate error

The database is unreachable or the role lacks permission to create tables. Check DATABASE_URL, that the database exists, and that the role can run DDL. Test with MELLOW_MIGRATE_ONLY=1 ./mellow.

sslmode errors connecting to the database

Use sslmode=require for a remote database, sslmode=disable only for a local socket. Managed providers usually require SSL.

Commands do not appear in Discord

• Global commands can take up to an hour to propagate the first time.
• Owner commands only appear in PRIVATE_GUILD_ID. Confirm that ID is correct and the bot is in that guild.
• Force a re-registration with MELLOW_FORCE_DEPLOY=1.

Commands appear but the bot cannot reply

Check the bot has Send Messages and Use Application Commands in that channel, plus Embed Links for most responses.

AI replies are always the same fixed text

ANTHROPIC_API_KEY is missing or invalid, or the Mellow config row has the AI disabled. Check /mellow view and /debug ai (owner-only).

Crisis screening never triggers

Screening only runs on DMs, mentions/replies, /crisis, and the context menu, and the message author must have crisis_detection enabled. It is also deliberately conservative.

"content could not be decrypted"

ENCRYPTION_KEY or ENCRYPTION_SALT_LIST changed without keeping the old salt. Restore the previous salt to ENCRYPTION_SALT_LIST (it can hold several) so old rows decrypt.

Shards keep reconnecting

Usually a network issue between the host and Discord, or Discord-side gateway problems. Shard close events are logged with the reason; check LOG_CHANNEL_ID output and LOG_LEVEL=debug.

HTTP API returns 401

POST /v1/chat and POST /v1/feedback need Authorization: Bearer <API_TOKEN>. GET /healthz and GET /v1/stats do not.

Getting help

• Owner diagnostics: /debug database, /debug ai, /debug version, /tools status, /tools logs.
• Support server and GitHub issues.