Docs: Errors | Zekken

Section 6 of 8

Errors

Error Kinds #

Zekken reports errors in a few consistent categories:

Syntax Error - source code cannot be parsed (unexpected/missing tokens).
Reference Error - a name cannot be resolved (variable/function/library/member).
Type Error - an operation or assignment has incompatible types.
Runtime Error - execution-time failures (I/O, invalid casts, out-of-range, etc.).
Internal Error - a compiler/interpreter bug or an internal stop-marker.

Error Output Layout #

Most CLI errors follow this layout:

Header: <Kind> Error: <message>
Location: file path + 1-based line/column
Snippet: the source line that triggered the error
Pointer: ^ marks the start column; ~ marks the span when known
Details (optional): expected/found, or a kind tag

Pointer Format #

Errors include line/column and a pointer. When Zekken can compute the token span, it draws a caret plus tildes (^~~~). When the span is unknown, you may see a single caret (^).

Reference Error: Variable 'numTerm' not found
     | main.zk -> [Ln: 16, Col: 20]
     |
  16 | startFibonacci => |numTerm|
     |                    ^~~~~~~
  kind: variable

Syntax errors happen before execution starts. They mean the parser could not build a valid AST from the source. Fix the first syntax error first, since later syntax errors may be caused by the first one.

Syntax Error: Expected value after '='
     | test.zk -> [Ln: 1, Col: 17]
     |
   1 | let a: string = ;
     |                 ^
  expected: a value
  found:    empty assignment

Common causes: missing values, missing closing |/]/}, or malformed call syntax.
What to do: fix the token the pointer highlights, then re-run to see the next error.

Reference Errors #

Reference errors mean a symbol could not be found in the current environment (or import scope). Zekken prints a kind tag to clarify what was being resolved.

Reference Error: Function 'add' not found
     | test.zk -> [Ln: 1, Col: 16]
     |
   1 | let sum: int = add => |2, 5|;
     |                ^~~
  kind: function

Common causes: typos, missing func declaration, missing use/include, or wrong export name.
What to do: declare the symbol earlier in the file, or import it from the correct module/file.

Type Errors #

Type errors occur when a declared type does not match the value, or when an operation is applied to incompatible types. These are detected during evaluation when the value becomes known.

Type Error: Type mismatch in variable declaration 'b'
     | test.zk -> [Ln: 1, Col: 17]
     |
   1 | let b: string = 10;
     |                 ^~
  expected: String
  found:    int

Common causes: wrong annotation (int vs float), assigning a different type later, invalid cast targets.
What to do: change the declared type, change the value, or cast the value when appropriate.

Runtime Errors #

Runtime errors happen during program execution (after parsing succeeds). They typically come from I/O, library calls, invalid casts, or invalid operations on values.

Runtime Error: Failed to read file 'test.txt': No such file or directory (os error 2)
     | test.zk -> [Ln: 4, Col: 40]
     |
   4 | let content: string = fs.read_file => |"test.txt"|;
     |                                        ^~~~~~~~~~

Common causes: missing files/paths, permissions, invalid arguments, unsupported operations.
What to do: verify external resources (files/dirs), validate inputs, and check library docs.

Internal Errors #

Internal errors indicate a bug in Zekken itself (or a stop-marker used internally to abort execution after collecting errors). If you see an internal error as a user-facing message, it is worth reporting with the smallest repro you can make.

What to do: try again with a minimized script; include the exact error output and Zekken version.
In development: run with RUST_BACKTRACE=1 for additional details.

Execution Behavior #

Parser errors are collected and printed before execution.
All error types (except internal) are reported with source context.
CLI run exits with non-zero status when errors exist.
os.exit => |code| exits process using that code in CLI mode.

Troubleshooting Tips #

If line/column seems off, verify nested call pipes are balanced: |...|.
If import/member access fails, verify module import form and method name case.

Zekken Documentation