Errors

The error classes the kernel throws.

Generated by bin/build_library_doc.py from the kernel sources. Do not edit by hand: change the generator, or the doc comments in kernel/src/, and re-run it.

Errors

CLASS Error

Abstract base class for the kernel error hierarchy.

Every throwable kernel error class extends Error (directly or transitively). User-defined error classes in consumer modules also extend Error to participate in RECOVER dispatch. The base class carries a single message field; subclasses add their own fields as needed (see ErrorTypes.ev for the kernel-shipped concrete classes).

────────────────────────────────────────────────────────────────── PANIC / RECOVER semantics ──────────────────────────────────────────────────────────────────

Every Error instance is THROWable. RECOVER clauses match by class type (and any subclass of the matched type — covariant). The base class is the catch-all:

TRY {
    doWork()
} RECOVER (FileError fe) {
    logError(fe.message)
} RECOVER (Error e) {
    // any error not handled above
    logError("unhandled: $1")->format(e.message)
}

The matching order is top-to-bottom; subclass clauses must precede their superclasses to be reachable.

────────────────────────────────────────────────────────────────── C++ INTEROP ──────────────────────────────────────────────────────────────────

At the C++ layer, Error extends std::exception so kernel errors propagate cleanly through any C++ stack frame the runtime traverses (FOREIGN-call-throwing, runtime panics, etc.).

_{kernel/src/Error.ev:49}

Constructors

INIT()

INIT(char32[] message)

INIT(REFERENCE String message)

Bridge from a String arg — copy the source's code points into this .message. The per-subclass INIT(String message) pattern uses SUPER(message) which routes here.

INIT(REFERENCE String message, REFERENCE String cause)

Chaining INIT — set both the message and the triggering error's message as the cause. Errors are chained by passing a triggering error's message as the cause of a new one (I.M.ii). A subclass that wants to expose chaining declares its own INIT(String, String) and routes here with SUPER(message, cause).

INIT(REFERENCE String message, REFERENCE String cause, int32 code)

Chaining INIT with an explicit numeric code.

Methods

METHOD hasCause() RETURNS boolean

Whether a triggering cause is attached (I.M.ii).

METHOD getErrorCode() RETURNS int32

The numeric error code; 0 means "no code" (I.M.ii).

CLASS CompileError

EXTENDS Error

Kernel error class. Thrown by tooling that performs compilation at runtime (the self-hosted Envzn compiler, opaque-evaluation helpers). Not expected to be thrown by ordinary application code, but reserved as a kernel type so compiler-using modules don't have to invent their own.

Subclass of Error; adds no new fields.

_{kernel/src/CompileError.ev:19}

Constructors

INIT(REFERENCE String message)

CLASS FileError

EXTENDS Error

Kernel error class. Thrown by File / Path methods on I/O failure. Examples: file not found, permission denied, disk full, directory creation failed, recursive remove encountered an undeletable entry.

Subclass of Error; adds no new fields — the type name itself is the discriminant for RECOVER dispatch.

_{kernel/src/FileError.ev:19}

Constructors

INIT(REFERENCE String message)

CLASS IndexOutOfBoundsError

EXTENDS Error

Kernel error class. Thrown by every collection's bounds check (Array.at / Array.setAt / Array.insertAt / Array.remove, LinkedList.insertAt / removeAt, etc.). The message field typically encodes the offending index and the collection's length at throw time; format follows the pattern "index $1 out of bounds for length $2".

Subclass of Error; adds no new fields.

_{kernel/src/IndexOutOfBoundsError.ev:20}

Constructors

INIT(REFERENCE String message)

CLASS MathError

EXTENDS Error

Kernel error class. Thrown by Math singleton methods on domain errors and by the checked-arithmetic helpers (Math.checkedAdd, etc.) on overflow. Examples: square root of a negative real, log of a non-positive value, integer-overflow on a checked op.

Subclass of Error; adds no new fields.

_{kernel/src/MathError.ev:19}

Constructors

INIT(REFERENCE String message)

CLASS NetworkError

EXTENDS Error

Historical kernel-side placeholder. The production NetworkError class lives in the Networking module (Networking/NetworkError.ev) where it belongs alongside the rest of the network-protocol error surface. This kernel-side declaration exists for C++ ABI symmetry with ENVZN.hpp.

Subclass of Error; adds no new fields.

_{kernel/src/NetworkError.ev:19}

Constructors

INIT(REFERENCE String message)

CLASS NullPointerException

EXTENDS Error

Thrown when an UNSAFE.* primitive's safety-wrapper detects a null pointer at dereference time.

the kernel-wide exception class the _UnsafeHandle<T>::operator->() and get() throw from. Caught by user code via TRY { ... } RECOVER (NullPointerException npe) { ... }, matching the standard kernel Error hierarchy.

Subclass of Error; adds no new fields. The probe at kernel_probe/unsafe_safety_wrapper/ validated that the throw unwinds across the FFI boundary and Envzn TRY/RECOVER catches by class identity.

_{kernel/src/NullPointerException.ev:24}

Constructors

INIT()

CLASS RandomError

EXTENDS Error

Kernel error class for the Random surface. Thrown by SecureRandom when OS entropy is unavailable, and by the generators on a non-positive bound (nextInt(bound <= 0)).

Subclass of Error; adds no new fields.

_{kernel/src/RandomError.ev:17}

Constructors

INIT(REFERENCE String message)

ENUM Severity

Per the ENVZN module convention, this single file holds the constitution's reserved enums. They're small (2–3 cases each) so grouping them in one file matches the pattern used for STRUCTs and INTERFACEs.

Each enum is referenced by name from the constitution and/or standard library: - DeliveryMode — used by CHANNEL[T]->send_message() to specify how a message reaches subscribers. - Severity — used by logging APIs and the constitution's Compiler-Error-Strategy spec to grade diagnostic levels. - Build — used by WHEN_BUILD conditional compilation to switch on debug-vs-release at compile time. Severity — diagnostic and logging level. Ordered (informally) from least to most serious. Consumers can compare ordinally via the implicit enum order.

• INFO — routine operational message.
• WARNING — something unexpected but recoverable.
• ERROR — operation failed; caller should handle.
• FATAL — unrecoverable; typical follow-up is exit() or PANIC.

Spec reference: §17 mentions ENVZN::Severity.WARNING for compiler-driven diagnostics; user-side logging follows the same enum.

_{kernel/src/enums.ev:39}