KAL diagnostics & limits

Every error family with real codes, the diagnostic shape, and the complete table of runtime limits.

Reading a diagnostic#

Compile and runtime errors arrive in one shape:

text

{ code, message, line, column, hint }

The builder renders them as "Line L:C — message" plus the 💡 hint. Example: saving a script without the header yields E001_MALFORMED_VERSION_HEADER on line 1 with the hint to put KAL VERSION 2.0; first.

The error families#

Family	Where	Meaning
`E001`–`E003`	Version gate	Missing/malformed header, unsupported version, source > 200k chars
`E101`–`E301`	Parser	Syntax errors with line/column
`S001`–`S011`	Semantics	Declarations, unresolved names, scopes, types, control flow, event context (S007), actions, schedules, rejected operators (S011)
`V2_COMPILER_*`	Bytecode gen	Internal targets/statements that cannot compile
`M001`–`M011`	Modules	Import problems — see Modules
`VM*`	Runtime	Sandbox violations during execution

Codes you will actually meet#

Code	What it means	Typical fix
`E001_MALFORMED_VERSION_HEADER`	Line 1 is not `KAL VERSION 2.0;`	Put the header on line 1 exactly
`E101_SYNTAX_ERROR`	Grammar violation	Read the line/column; check the statement's exact shape in these guides
`S002_UNRESOLVED_IDENTIFIER`	Unknown name	Declare it, or fix the spelling
`S004_TYPE_MISMATCH`	Wrong type for the position	Adjust the declared type or value
`S007_INVALID_EVENT_CONTEXT`	Variable not available in this trigger	Use only the trigger's context (see the table in Triggers)
`S009_INVALID_SCHEDULE`	Bad schedule form	`SCHEDULE EVERY <ms>` or `SCHEDULE AFTER "<dur>"`
`S011_UNSUPPORTED_OPERATOR`	`MATCHES`/`HAS_ROLE`/`HAS_PERMISSION`	Replace with `CONTAINS`/`IN` over `member.roles`
`M001_MODULE_NOT_FOUND`	Import target not registered	See Modules

Runtime (VM) errors#

At run time the sandbox enforces the budget:

Code	Meaning
`EXECUTION_TIMEOUT`	The 5-second wall clock expired
`INSTRUCTION_LIMIT_EXCEEDED`	More than 50,000 VM instructions
`CALL_DEPTH_LIMIT_EXCEEDED`	Recursion past 64 frames
`DIVISION_BY_ZERO`	`/` or `%` by zero
`TYPE_CHECK_FAILURE`	Wrong operand types at runtime
`STATE_ACCESS_ERROR`	State value not JSON-able or over its size limit
`ACTION_EXECUTION_FAILURE`	A Discord action failed (carries the action type and line)
`EXPLICIT_THROW`	A `THROW` was not caught

The complete limit table#

Resource	Limit
Source length	200,000 characters
String literal	65,536 characters
Identifier length	128 characters
Tokens	50,000
Parse depth	256
VM instructions	50,000
Wall clock	5 seconds
Call depth	64
Operand stack	1,000
Array length	10,000
Map entries	10,000
String length at runtime	1,000,000 chars
Discord actions per run	5
Timeout duration	28 days
Ban message-deletion window	≤ 7 days (604,800 seconds)
Purge count	1–100
Components	5 rows × 5; select menus ≤ 25 options; ids ≤ 100 chars; labels ≤ 80
State	100 keys / 2,048-byte values / 512 KiB per script / keys ≤ 256 chars
Imports	32 per script; modules 256 per server; module source 200,000 bytes
Active locks	10,000
Rate buckets	10,000

Debugging workflow#

Check syntax in the builder — validate-only compile, no side effects.
Run simulation — a sandboxed dry run with a mock user; inspect the recorded actions and any error.
LOG / INSPECT — leave breadcrumbs in scripts under development: INSPECT result prints a structured dump of the value at that point.
INTO capture — capture risky actions and branch on outcome.ok instead of letting failures crash the run.