Understanding Hades Error Messages and Diagnostics

When Hades encounters a problem it prints a richly formatted diagnostic that tells you the error type, a human-readable message, the exact source line, and a red caret (^) pointing to the column where the fault was detected. Errors are separated into two families: syntax errors, which are raised during lexing or parsing before any code runs, and runtime errors, which are raised by the interpreter during execution.

Error Format

Every error follows the same visual structure, produced by the f_error function in helpers.py:

-- Syntax Error ------------------------
Error: <message>
Line N:
      <source line, underlined>
      ^   ← red caret at the error column
----------------------------------------

The header line names the error family (Syntax Error or Runtime error).
Error shows the message in bold red.
Line N is the 1-based line number in your source file.
The source line is printed underlined so you can identify it at a glance.
The red ^ caret sits directly beneath the offending character.

Syntax Errors

Syntax errors are raised either by the Lexer (during tokenisation) or the Parser (during grammar analysis). The program never starts executing when a syntax error is present.

Lexer Errors

Unexpected character

Triggered when the lexer encounters a character it does not recognise.

x: int = 10 @ 2;

-- Syntax Error ------------------------
Error: Unexpected character: @
Line 1:
      x: int = 10 @ 2;
                   ^
----------------------------------------

Unterminated string literal

Raised when a string opened with ' reaches end-of-file without a closing '.

name: str = 'Hades;

-- Syntax Error ------------------------
Error: Unterminated string literal
Line 1:
      name: str = 'Hades;
                  ^
----------------------------------------

Invalid float

Raised when a numeric literal contains more than one decimal point.

x: float = 3.14.15;

-- Syntax Error ------------------------
Error: Invalid float
Line 1:
      x: float = 3.14.15;
                     ^
----------------------------------------

Parser Errors

Expected ';' to terminate the statement

Every statement that is not a block ({}) must end with a semicolon.

x: int = 5
y: int = 10;

-- Syntax Error ------------------------
Error: Expected ';' to terminate the statement, but found 'int'
Line 2:
      y: int = 10;
      ^
----------------------------------------

Expected ')' to close the expression

A parenthesised expression or function call was not closed.

result: int = (10 + 5;

-- Syntax Error ------------------------
Error: Expected ')' to close the expression, but found ';'
Line 1:
      result: int = (10 + 5;
                           ^
----------------------------------------

Expected '}' to close the block

A block opened with { was not closed before a new statement or end of file.

if (TRUE) {
    print('ok');

x: int = 1;

-- Syntax Error ------------------------
Error: Expected '}' to close the block, but found 'int'
Line 4:
      x: int = 1;
      ^
----------------------------------------

Unterminated block

A block opened with { reached end-of-file without ever being closed.

func greet(name: str) => nothing {
    print(name);

-- Syntax Error ------------------------
Error: Unterminated block, expected '}' but reached end of input
Line 2:
      print(name);
                  ^
----------------------------------------

Runtime Errors

Runtime errors (InterpreterError) occur during execution. They carry the source token that triggered the fault, so the caret always points to the right place.

Undefined Variable

Raised when you read a variable name that has not been declared in the current scope.

result: int = total + 1;

-- Runtime error ------------------------
Error: Undefined variable 'total'
Line 1:
      result: int = total + 1;
                    ^
----------------------------------------

Did You Mean?

When the interpreter cannot find a variable it uses difflib.get_close_matches to search all variables currently in scope and suggest the closest match. The cutoff similarity threshold is 0.6.

counter: int = 0;
counter = couner + 1;

-- Runtime error ------------------------
Error: Undefined variable 'couner'. Did you mean 'counter'
Line 2:
      counter = couner + 1;
                ^
----------------------------------------

The “did you mean” suggestion only fires when a sufficiently close name is found in the current scope. If the variable is declared in an outer scope that is no longer visible, the suggestion will not appear.

Cannot Assign to Undeclared Variable

Raised when you try to assign to a name that was never declared with a type hint.

score = 100;

-- Runtime error ------------------------
Error: Cannot assign to undeclared variable 'score'
Line 1:
      score = 100;
      ^
----------------------------------------

Declare the variable first:

score: int = 0;
score = 100;

Division by Zero

Raised for both / and % operations when the right-hand side evaluates to zero.

x: int = 10 / 0;

-- Runtime error ------------------------
Error: Division by zero
Line 1:
      x: int = 10 / 0;
                  ^
----------------------------------------

Invalid Operand Types

Raised when an operator is applied to incompatible types, such as adding a number to a string.

x: int = 5 + 'hello';

-- Runtime error ------------------------
Error: Invalid operand types for PLUS: int and str
Line 1:
      x: int = 5 + 'hello';
                 ^
----------------------------------------

List Index Out of Range

Raised when you access an index that does not exist in the list.

nums: list = [1, 2, 3];
val: int = nums -> 10;

-- Runtime error ------------------------
Error: List index 10 out of range (length 3)
Line 2:
      val: int = nums -> 10;
                      ^
----------------------------------------

Type Mismatch

Raised when a value assigned to a typed variable does not match the declared type hint.

count: int = 'five';

-- Runtime error ------------------------
Error: Type mismatch for 'count': expected int, but got str
Line 1:
      count: int = 'five';
      ^
----------------------------------------

Type mismatches are also caught for function parameters and return values.

Function Argument Count Mismatch

Raised when a function is called with the wrong number of arguments.

func add(a: int, b: int) => int {
    => a + b;
}

result: int = add(1, 2, 3);

-- Runtime error ------------------------
Error: 'add' expects 2 arguments, but got 3
Line 5:
      result: int = add(1, 2, 3);
                    ^
----------------------------------------

Calling a Non-Callable

Raised when you attempt to call a variable as if it were a function.

x: int = 42;
x();

-- Runtime error ------------------------
Error: 'x' is not callable
Line 2:
      x();
      ^
----------------------------------------

Cannot Iterate Over Non-List/String

Raised when a for … in loop is given a value that is neither a list nor a str.

n: int = 5;
for (i: int; i in n) {
    print(i);
}

-- Runtime error ------------------------
Error: Cannot iterate over type 'int'
Line 2:
      for (i: int; i in n) {
                       ^
----------------------------------------

Cannot Redefine a Function

Raised when a func definition uses a name that already exists in the current scope.

func greet() => nothing {
    print('Hello');
}

func greet() => nothing {
    print('Hi');
}

-- Runtime error ------------------------
Error: Cannot redefine 'greet'
Line 5:
      func greet() => nothing {
           ^
----------------------------------------

Summary Table

Error	Phase	Common Cause
Unexpected character	Lexer	Invalid symbol in source (e.g. `@`, `#`)
Unterminated string literal	Lexer	Missing closing `'`
Invalid float	Lexer	Multiple decimal points in a number
Expected `';'`	Parser	Missing semicolon at end of statement
Expected `')'`	Parser	Unclosed parenthesis in expression or call
Expected `'}'`	Parser	Unclosed block body
Unterminated block	Parser	EOF inside a `{...}` block
Undefined variable	Runtime	Variable read before declaration
Cannot assign to undeclared	Runtime	Assignment without prior `name: type = …` declaration
Division by zero	Runtime	Divisor evaluates to `0`
Invalid operand types	Runtime	Operator used on incompatible types
List index out of range	Runtime	Index `≥ len(list)` or `< -len(list)`
Type mismatch	Runtime	Value does not match declared type hint
Argument count mismatch	Runtime	Wrong number of arguments in function call
Not callable	Runtime	`()` applied to a non-function variable
Cannot iterate	Runtime	`for … in` over a non-list, non-string value
Cannot redefine function	Runtime	`func` declaration with a name already in scope

Get Started

Language Guide

Tooling

Understanding Hades Error Messages and Diagnostics

Error Format

Syntax Errors

Lexer Errors

Parser Errors

Runtime Errors

Undefined Variable

Did You Mean?

Cannot Assign to Undeclared Variable

Division by Zero

Invalid Operand Types

List Index Out of Range

Type Mismatch

Function Argument Count Mismatch

Calling a Non-Callable

Cannot Iterate Over Non-List/String

Cannot Redefine a Function

Summary Table

Build docs developers (and LLMs) love

Get Started

Language Guide

Tooling

Documentation Index

​Error Format

​Syntax Errors

​Lexer Errors

​Parser Errors

​Runtime Errors

​Undefined Variable

​Did You Mean?

​Cannot Assign to Undeclared Variable

​Division by Zero

​Invalid Operand Types

​List Index Out of Range

​Type Mismatch

​Function Argument Count Mismatch

​Calling a Non-Callable

​Cannot Iterate Over Non-List/String

​Cannot Redefine a Function

​Summary Table

Build docs developers (and LLMs) love

Error Format

Syntax Errors

Lexer Errors

Parser Errors

Runtime Errors

Undefined Variable

Did You Mean?

Cannot Assign to Undeclared Variable

Division by Zero

Invalid Operand Types

List Index Out of Range

Type Mismatch

Function Argument Count Mismatch

Calling a Non-Callable

Cannot Iterate Over Non-List/String

Cannot Redefine a Function

Summary Table