Errors
The error classes the kernel throws.
Generated by
bin/build_library_doc.pyfrom the kernel sources. Do not edit by hand: change the generator, or the doc comments inkernel/src/, and re-run it.
Errors
CLASS Error
Abstract base class for the kernel error hierarchy.
Every 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 can be raised in a PANIC. RECOVER clauses match by class type (and any subclass of the matched type — covariant). The base class will recover from any panic:
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-raising, runtime panics, etc.).
kernel/src/Error.ev:49
Fields
int32 codeint32 line_number
Constructors
INIT()
INIT(char32[] message)
INIT(REFERENCE String message)
Bridge from a String arg — copy the source's code points
into this .msg. 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).
METHOD message() RETURNS String
What went wrong, as the PANIC site's INIT set it.
METHOD cause() RETURNS String
The triggering error's message, or empty when there is none (I.M.ii).
METHOD filename() RETURNS String
The source file of the PANIC site, injected by the compiler.
METHOD threadName() RETURNS String
The raising thread's name, or empty for an unnamed context.
CLASS CompileError
EXTENDS Error
Kernel error class. Raised by tooling that performs compilation at runtime (the self-hosted Envzn compiler, opaque-evaluation helpers). Not expected to be raised 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:23
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. Raised 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 PANIC time; format follows the pattern
"index $1 out of bounds for length $2".
Subclass of Error; adds no new fields.
kernel/src/IndexOutOfBoundsError.ev:24
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 EmptyHandleError
EXTENDS Error
Raised when a handle is used while it holds nothing.
Two places raise it. The _UnsafeHandle<T>::operator->() and get()
safety wrapper raises it (no message) when an UNSAFE.* handle is
dereferenced while null. Kernel code raises it (with a message) from a
guard that refuses to read a value it knows was moved out — CollisionNode's
valid flag. Recover from the PANIC in user code via
TRY { ... } RECOVER (EmptyHandleError e) { ... }, like any kernel Error.
Subclass of Error; adds no new fields. The probe at
kernel_probe/unsafe_safety_wrapper/ validated that the raised PANIC
unwinds across the FFI boundary and Envzn TRY/RECOVER recovers by
class identity.
kernel/src/EmptyHandleError.ev:25
Constructors
INIT()
INIT(REFERENCE String message)
With a message naming the handle that was empty.
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)
CLASS OutOfMemoryError
EXTENDS ResourceExhaustedError
Kernel error class. Raised when the runtime allocator cannot get a block; the message
is "out of memory allocating
Subclass of ResourceExhaustedError; adds no new fields.
kernel/src/OutOfMemoryError.ev:24
Constructors
INIT(REFERENCE String message)
CLASS ResourceExhaustedError
EXTENDS Error
Kernel error class. The parent of every error that means the program ran
out of a finite resource (memory, the stack) rather than did something wrong.
RECOVER (ResourceExhaustedError e) handles all of them.
Subclass of Error; adds no new fields.
kernel/src/ResourceExhaustedError.ev:20
Constructors
INIT(REFERENCE String message)
CLASS CloneError
EXTENDS Error
Raised when clone() is asked to copy a value that has no copy.
One place raises it today: clone() of an opaque that carries a C
handle (a FOREIGN_TYPE pointer such as a sqlite3_stmt*). A C object
has one owner, and copying the pointer would make two, one of which frees
it under the other (I.D.v (c)). Keep one owner and lend it with
REFERENCE. Raised from the kernel's opaque runtime, which is where the
box knows what it carries; caught like any kernel Error, with
TRY { ... } RECOVER (CloneError e) { ... }.
kernel/src/CloneError.ev:21
Constructors
INIT(REFERENCE String message)
CLASS LensMismatchError
EXTENDS Error
Kernel error class. Raised when a checked narrowing (:= or =@ from a parent or interface type to a narrower one) finds the object's class is not the one named. The message names both types.
Subclass of Error; adds no new fields.
kernel/src/LensMismatchError.ev:19
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
| Case | Description |
|---|---|
? |
— |
? |
— |
? |
— |
? |
— |