Evidence BotTroubleshooting

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=true temporarily 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

SymptomChecks and next steps
Bot cannot log inVerify TOKEN, internet access and Node.js version. Get a new token if it was reset.
Disallowed-intent errorEnable Message Content Intent in the Developer Portal, then restart.
Commands missingCheck GUILD_ID, the bot and applications.commands install scopes, startup registration and member command permissions.
Staff command deniedThe user needs a role in STAFF_ROLE_IDS or Administrator permission. Blank roles allow only administrators.
Invalid forum errorSet FORUM_CHANNEL_ID to a Forum channel ID in the intended server, not a text channel or thread.
Forum creation failsCheck the forum ID, channel permissions and that all required status tags exist.
Follow-up or resolution cannot be postedCheck thread visibility, Send Messages in Threads, and whether the thread is locked or archived. Manage Threads may be needed.
Log or reminder messages missingVerify the channel IDs and the bot's permissions in those channels.

Punishment imports & appeals

SymptomChecks and next steps
Appeal ignoredCheck the configured channel, allowlisted webhook ID or staff author, exact embed title and author, and all required fields.
Old punishments not importedAn existing cursor may already be saved, or PUNISHMENT_IMPORT_EXISTING=false is using its default. See Backfilling old punishments.
MySQL import failedCheck 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 failsCompare 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

SymptomChecks and next steps
Migration refuses to runStop the running bot or process manager, then examine the lock PID.
Corrupt case storeStop the bot and restore a verified backup.
Another bot instance is already runningStop the existing process named in the message. Confirm it has stopped before removing a stale lock.
Addon commands say unavailableCheck the console for that addon's start error, fix its config.json and restart.
An addon website's OAuth sign-in fails after a restartCheck 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.