Troubleshooting: Find the Cause and Fix of Problems

Something does not work and you do not know why? Troubleshooting checks your server for the most common causes and shows for every finding what is wrong and how to fix it. If you also describe the problem in your own words, Kage AI helps evaluate it and names likely causes and steps. Kage changes nothing itself: you carry out the steps.

A short walkthrough is in the guide Analyse Discord bot problems. Ongoing monitoring is described in Monitoring.

Requirements

• Manage Server permission: Troubleshooting is for people with the full Manage Server permission.
• Kage is on the server. Otherwise Kage cannot read anything and reports that as the only finding.
• For the AI evaluation: a server with free Kage AI answers in its allowance and your consent to the data transfer.

How to start it

1. In the dashboard open Troubleshooting (sidebar). On a red module you get there directly via Open troubleshooting, with that module preselected.
2. Optionally describe what does not work, for example "New members do not get a role".
3. Optionally choose a module if the problem concerns one.
4. For the AI evaluation tick Evaluate with Kage AI and agree to the transfer. The description needs a few words for this.
5. Press Start analysis. After a fix in Discord or the dashboard, run it again.

Stage 1: findings

The check runs without AI on Kage's systems and costs nothing. It finds:

Every finding has an explanation, a concrete fix and a link to the module. Findings are split into problems (red) and hints.

Stage 2: evaluation by Kage AI

With your consent the AI receives the description, the findings and the state of your modules and returns:

• a summary in two sentences,
• possible causes with certainty: *certain* (findings or data prove it), *likely* or *possible*,
• steps to a solution, often with a link to the module,
• up to two follow-up questions if details are missing. Add the answers to the description and run it again,
• matching help articles as sources.

Rate the evaluation with 👍 or 👎. It is labelled as AI output and may be wrong.

If the AI is down, the allowance is empty or the answer is unusable, you get the findings and matching help articles, never an invented answer.

Privacy

The check of the findings sends nothing to the AI. For the evaluation, and only with your consent, the following go to the AI provider (currently Anthropic PBC, USA): the cleaned problem description, the findings and for each module its name, state and settings (channels and roles as names, texts shortened) plus counters of how often the module triggered something in the last 14 days. Not sent are messages, members, event texts, credentials and the server ID. Kage first removes email addresses, web addresses, Discord IDs and keys; it does not detect names. Only the cleaned description without identifier is stored, for 90 days, together with your rating. Your consent is recorded in the administration log. Details: privacy policy.

Allowance

An AI evaluation counts as one Kage AI answer against your server's monthly allowance (Basic 150, Premium 600, Enterprise 1500) and the daily limit per person. The check of the findings is unlimited. The page shows how many answers are left.

Limits

• Kage changes nothing itself. Permissions and role order are also set by you in Discord.
• The analysis sees settings and counters but no messages. Why a particular message was not posted it can only infer from permissions, channels and settings.
• Not every module has check rules. If a module is missing from the findings, that does not mean it runs without errors.
• The AI can be wrong. Treat its causes as hints and verify them.

Settings overview

Troubleshooting has no settings. The module choice and the description apply only to the respective analysis.

Common errors

"Please agree to the transfer first"

For the AI evaluation you need the second tick box. Without consent only the check of the findings runs.

"Please describe the problem a bit more precisely"

The AI evaluation needs at least a few words. Describe what happens and what you expect.

The AI evaluation cannot be selected

No AI answer is free for the server: the allowance or daily limit is reached, or the AI is switched off. The findings are still available.

"Kage cannot reach your server"

Check in Discord that Kage is on the server. If not, invite the bot again with the link on the dashboard home page.

No findings are shown but nothing works

Describe the problem with the AI evaluation and choose the module. Also look at the module's Logs tab to see what happened last.

Further reading

Monitoring, Kage's permissions, role order and AI Setup.