Troubleshooting & reference About 3 min read

Troubleshooting

Systematic diagnosis for silent commands, permission errors, KAL compile errors and dashboard failures.

Nothing responds#

Is the module enabled? (,help shows what is on.)
Is the command enabled inside the module?
Is the server kill-switched? Only ,enable works then — use it.
Is the prefix what you think it is? (,prefix.)
Does the bot have View Channel + Send Messages there?

Ordinary commands that are switched off fail silently by design; management commands always explain themselves.

A moderation command errors with a permission message#

Two different permissions are in play:

Your permission — ,ban needs your Ban Members.
The bot's permission — the bot needs it too, plus a higher role than the target. Missing bot permissions surface as Discord API errors; missing role height refuses with a clear message.

Dashboard problems#

Symptom	Cause and fix
Server missing from the list	You are not owner/Administrator on it — see Account & access
"You don't have access to this server"	The same guard, via URL
Save fails, "bot offline"	`bot_unavailable` (503) — the dashboard never saves while the bot is down; retry later
Settings look stale	Pages render the bot's last cached state; reconnecting refreshes it

KAL compile errors#

Start with the code family:

E001_MALFORMED_VERSION_HEADER — add KAL VERSION 2.0; on line 1.
E101_SYNTAX_ERROR — grammar; compare with a verified example from the KAL guides.
S007_INVALID_EVENT_CONTEXT — you used a variable this trigger does not provide; check the context table in Triggers.
S011_UNSUPPORTED_OPERATOR — MATCHES/HAS_ROLE/HAS_PERMISSION do not exist; use CONTAINS/IN.
M0xx — module import problems; see Modules.

Then use the builder's Check syntax (compiles without side effects) and Run simulation (sandboxed dry run) — both print line, column and hint.

KAL runtime errors#

Symptom	Meaning
`EXECUTION_TIMEOUT`	The run exceeded 5 seconds — break work into schedules
`INSTRUCTION_LIMIT_EXCEEDED`	Loop too large; add bounds or `BREAK`
`ACTION_EXECUTION_FAILURE`	A Discord action failed; capture with `INTO` and inspect `outcome.ok`
State errors	Value over 2,048 bytes or key limits — see State

Remember: a crashed run rolls back its state writes — fix the script and re-run; nothing is half-applied.

Security or stats not doing anything#

Security needs the module and the specific feature enabled, and the author must not be exempt (admins/Manage Messages/Manage Server always are).
Server Stats channels only update on the configured interval (≥ 10 minutes) and only voice/stage channels are ever renamed — that is a Discord limit.

Still stuck#

Common setup problems covers the first-hour issues, and the command reference doubles as a checklist of what exists.