Evidence Bot Troubleshooting & Diagnostics
Diagnose Evidence Bot login, Discord permissions, slash commands, forum access, MySQL imports, appeals, migrations and addon errors.
Evidence Bot Troubleshooting & Diagnostics
Start with the first relevant console error. Check the bot's configuration and Discord channel permissions before changing stored case data.
Read the console
The bot prints concise INFO, WARN and ERROR lines. Common Discord, MySQL, network and file errors are translated into plain language with a suggested next action.
- Identical background import errors are deduplicated for a minute to prevent repeated console noise.
- Known tokens, passwords and environment secrets are redacted from log output.
- Set
DEBUG_ERRORS=truetemporarily to include developer stack traces when you need them for support.
Run the built-in checks
npm test
npm audit
Automated tests use temporary data and mocked Discord and MySQL responses. A real installation still needs the first-run checklist as a smoke test.
Startup & Discord
| Symptom | Checks and next steps |
|---|---|
| Bot cannot log in | Verify TOKEN, internet access and Node.js version. Get a new token if it was reset. |
| Disallowed-intent error | Enable Message Content Intent in the Developer Portal, then restart. |
| Commands missing | Check GUILD_ID, the bot and applications.commands install scopes, startup registration and member command permissions. |
| Staff command denied | The user needs a role in STAFF_ROLE_IDS or Administrator permission. Blank roles allow only administrators. |
| Invalid forum error | Set FORUM_CHANNEL_ID to a Forum channel ID in the intended server, not a text channel or thread. |
| Forum creation fails | Check the forum ID, channel permissions and that all required status tags exist. |
| Follow-up or resolution cannot be posted | Check thread visibility, Send Messages in Threads, and whether the thread is locked or archived. Manage Threads may be needed. |
| Log or reminder messages missing | Verify the channel IDs and the bot's permissions in those channels. |
Punishment imports & appeals
| Symptom | Checks and next steps |
|---|---|
| Appeal ignored | Check the configured channel, allowlisted webhook ID or staff author, exact embed title and author, and all required fields. |
| Old punishments not imported | An existing cursor may already be saved, or PUNISHMENT_IMPORT_EXISTING=false is using its default. See Backfilling old punishments. |
| MySQL import failed | Check provider credentials, SELECT grants, TLS configuration, exact table prefix and name, and the plugin schema. Failed rows are retried. |
/mycases is empty or appeal ownership fails | Compare the stored Discord identity to the caller's ID. Use a real mention or ID when filing; imported records have no Discord identity. |
Data, migration & addons
| Symptom | Checks and next steps |
|---|---|
| Migration refuses to run | Stop the running bot or process manager, then examine the lock PID. |
| Corrupt case store | Stop the bot and restore a verified backup. |
| Another bot instance is already running | Stop the existing process named in the message. Confirm it has stopped before removing a stale lock. |
| Addon commands say unavailable | Check the console for that addon's start error, fix its config.json and restart. |
| An addon website's OAuth sign-in fails after a restart | Check whether its port auto-assigned a new value. Update the registered Discord redirect and reverse-proxy rule to match. |
For stored records or host migrations, see Maintenance & Backups. For language-file issues, see Customizing Evidence Bot Translations. If the issue persists, share the relevant error and bot version through ZCraft Studios support. Never share tokens, passwords or private evidence.