Skip to content

Diagnostics

Every tool emits diagnostics as JSON when called with --json, one object per line:

{"code":"T001","severity":"error","file":"a.aph","line":3,"col":14,"node":"n42","msg":"type mismatch","expected":"i64","found":"str"}
Field
code, severity, file, line, col, msg always present; msg is short and lowercase
node the AST node, as numbered by aleph ast (n0, n1, … in pre-order)
expected, found for type and example errors
fix {"op":"replace","node":"n42","with":"..."}, only when the fix is certain
canonical for F codes: the canonical text to use instead
Prefix Stage
L lexical
P parse
F format / canonical form
T type
C capability
E examples
R runtime trap
X tool usage
Code Meaning
L001 invalid character
L002 invalid token
P001 unexpected token
P002 wrong number of arguments
P003 unknown function
F001 not in canonical form (includes canonical)
T001 type mismatch
T005 shadowed binding
T010 cannot infer the type of ok, err or none
E001 missing examples
E002 example failed (includes expected and actual)
C001 missing capability
C002 path not covered by a capability
C003 invalid capability prefix
R001–R005 runtime traps, see Runtime

The complete list is in spec/diagnostics.md in the repository.