Diagnostics Reference

Reference for compiler and runtime error messages produced by the Braid toolchain.

Parse Errors

Errors detected during the lexing and parsing phases. The compiler reports the file, line, and column where the error was detected.

Unexpected Token

// Source:
fn main() {
    let x = @ 42
}

// Error:
// error at line 2, col 13: unexpected token in expression: '@' (type 42)

Cause: The token at the reported position does not match any valid expression start. This typically indicates a syntax error or typo.

Fix: Check the expression at the reported location for missing operators, misplaced symbols, or typos.

Expected Semicolon

// Source:
fn main() {
    let x = 42
    let y = 10
}

// Error:
// error: expected token type TOK_SEMICOLON, got TOK_LET

Cause: A statement separator (;) is missing between two statements. Braid requires semicolons after expression statements and variable declarations.

Fix: Add ; at the end of each statement. Variable declarations with let and expression statements both need semicolons.

Missing Closing Brace

// Source:
fn main() {
    if true {
        print("hello")
    // missing closing brace for if

// Error:
// error: unexpected content in block body
// or reaches EOF without closing braces

Cause: A block () is not properly closed. The parser reaches the end of the file or encounters unexpected tokens while looking for the closing brace.

Fix: Ensure every { has a matching }. Check indentation to spot mismatched braces.

Unknown Decorator

// Source:
@unknown_decorator fn foo() {}

// Error:
// error: unknown decorator '@unknown_decorator'

Cause: The identifier following @ is not a recognized decorator. Only @autograd and @layer are supported.

Fix: Use @autograd for automatic differentiation functions or @layer for neural network layer structs.

Expected Type Identifier

// Source:
fn add(x: 42) -> int { return x }

// Error:
// error: expected type identifier, got '42'

Cause: A type annotation position contains something other than a type identifier.

Fix: Use a valid type name (int, float, bool, string, or a user-defined struct/enum name).

Type Errors

Errors from the Hindley-Milner type checker during type inference and unification.

Undefined Variable

// Source:
fn main() {
    print(undefined_var)
}

// Error:
// error: undefined variable 'undefined_var' at line 2, col 11

Cause: A variable name is used that has not been declared in the current scope.

Fix: Declare the variable with let before using it, or check the name for typos.

Type Mismatch

// Source:
fn add(x: int, y: string) -> int {
    return x + y
}

// Error:
// error: type mismatch: cannot apply '+' to 'int' and 'string'
// or: error: cannot unify 'int' with 'string'

Cause: An operation is applied to operands of incompatible types. The + operator works on two ints, two floats, or string concatenation, but not mixed types.

Fix: Ensure operands have compatible types. Use explicit conversion or fix the type annotation.

Return Type Mismatch

// Source:
fn get_flag() -> int {
    return true
}

// Error:
// error: expected return type 'int', got 'bool'

Cause: The returned expression type does not match the function's declared return type.

Fix: Either change the return type annotation or fix the return expression to match.

Nil Comparison Error

// Source:
fn check(val: string) {
    if val > nil {
        print("greater")
    }
}

// Error:
// error: cannot compare 'string' with 'nil' using '>'

Cause: Comparison operators (<, >, <=, >=) cannot compare non-numeric types with nil.

Fix: Use == nil or != nil for nil checks.

Runtime Errors

Errors that occur during bytecode execution in the BraidVM.

Index Out of Bounds

// Source:
fn main() {
    let arr = [10, 20, 30]
    print(arr[5])
}

// Error:
// runtime error: index 5 out of bounds for array of length 3

Cause: An array or tensor access uses an index that exceeds the valid range.

Fix: Check indices before access, or use len() to verify bounds.

Nil Access

// Source:
fn main() {
    let obj = nil
    print(obj.field)
}

// Error:
// runtime error: attempted to access field of nil value

Cause: A field access (.) or method call is performed on a nil value.

Fix: Check for nil before accessing fields: if obj != nil { print(obj.field) }.

Division by Zero

// Source:
fn main() {
    let x = 10 / 0
}

// Error:
// runtime error: division by zero

Cause: Integer or float division by zero.

Fix: Check the divisor before division: if b != 0 { return a / b } else { return nil }.

Corrupt Bytecode

braidc run corrupt.bx
// error: corrupt .bx payload

Cause: The .bx file has an invalid header (bad magic, wrong version, or truncated payload).

Fix: Rebuild the bytecode from source: braidc build source.br -o output.bx.

Unsupported Target Kind

braidc run unsupported.bx
// error[BX-RUN-UNSUPPORTED-TARGET]: unsupported target kind

Cause: The .bx file has a target kind value that the current BraidVM does not support (e.g., a newer format version).

Fix: Rebuild the bytecode with the same version of braidc that will execute it.