Development documentation · Some APIs may be unreleased Published release →

Guides

Terminal faults and codes

A host-visible runtime Fault carries a machine-readable code as well as its diagnostic message and execution location. This is a host API; guest programs cannot catch a Fault or select its code.

Explicit faults from guest code

System.Panic(message: string) -> unit terminates the invocation with UserFault. The explicit neoIL fault "message" instruction has the same code. There is no code argument or overload. A message such as StackOverflow remains a UserFault; the runtime never infers the classification from guest-supplied text. Explicit fault calls in guest library code also use UserFault.

Use Result for expected errors that callers can handle. A stream's Closed result or a Task's cancelled state is not a terminal Fault. These codes do not introduce exceptions, catch/finally behavior or a new guest error hierarchy.

The native source library raises the same UserFault. Raven's RuntimeFailureContract identifies the terminal function so constructs such as let-else recognize that a Fail call does not return. Use the matching compiler and runtime contract; an incompatible terminal-function owner is rejected before output.

Reading faults in an embedding host

Rust hosts receive Result<Execution, neoclr::Fault>. The Fault fields are:

Field Type and purpose
code neoclr::FaultCode; runtime-assigned classification
message String; human diagnostic text, not a stable discriminator
function Optional<String>; faulting function when available
instruction Optional<usize>; instruction index when available
stack_trace Optional<StackTrace>; owned execution frames; may be absent before execution

FaultCode is a copyable, comparable, hashable, non-exhaustive Rust enum. Match known variants with a fallback for future additions. FaultCode::as_str() returns a stable, case-sensitive identifier. Display and Serde serialization use that same string. Enum ordinals are not an API, and these are not .NET HRESULT values.

match program.run(neoclr::Limits::default()) {
    Ok(execution) => { /* consume the result */ }
    Failure(fault) => match fault.code {
        neoclr::FaultCode::StackOverflow => { /* report excessive call depth */ }
        neoclr::FaultCode::UserFault => { /* report an explicit guest failure */ }
        _ => { /* handle another terminal failure */ }
    },
}

The code is selected at the failure site, independently of message formatting. Stack-trace capture and worker error propagation retain it. A host that constructs Fault values itself is trusted host code; this is not a guest capability.

Codes

Stable identifier / Rust variant Meaning
UserFault Explicit guest fault instruction or System.Panic call, including guest library calls
StackOverflow Configured interpreter call-frame limit exhausted, including a zero-frame budget
EvaluationStackOverflow Configured evaluation/operand-stack limit exhausted
InstructionLimitExceeded Invocation instruction budget exhausted
ExecutionCancelled Host cancellation or debugger stop, not guest Task cancellation
DivideByZero Integer divide or remainder with a zero divisor
ArithmeticOverflow Checked integer arithmetic or conversion overflow; also signed minimum divided by minus one
NullReference Null managed object, array or interface dereference, including value unboxing
InvalidCast Unboxing a value whose concrete boxed type differs from the requested type
NullPointer Null native pointer dereference
IndexOutOfRange Managed array index outside its range
HeapLimitExceeded Managed heap object or identity budget exhausted
ArrayLimitExceeded Managed array payload budget or supported length exceeded
NativeMemoryLimitExceeded Native pointer heap byte or allocation budget exhausted
InternPoolLimitExceeded String intern entry or unique UTF-8 payload budget exhausted
InvalidProgram Classified verifier failures or execution falling through without a return
RuntimeError Other runtime, loader or host failures not yet assigned a narrower category

Classification is being introduced incrementally: not every old diagnostic has a specialized code yet. Consumers must handle RuntimeError and unknown future values. StackOverflow here describes the interpreter's checked frame limit; it does not claim to catch a Rust/OS stack overflow or an arbitrary host process failure.

CLI and debugger

CLI execution faults with a captured stack use the shared Fault::diagnostic() format: Code: message, then at Function [instruction N]. They exit 1. Normal completion preserves the program's exit code, including a deliberate 1; diagnostic stderr distinguishes an unhandled fault. Standard runtime messages come from the code catalog; user messages are preserved. Loader/verifier errors before execution retain their detailed format. Embedding hosts should inspect the structured fault fields rather than parse CLI diagnostic text.

Debugger snapshots retain the existing fault diagnostic and add fault_code: "StackOverflow". fault_code is null when there is no terminal fault. It is populated for execution faults, pre-execution failures, cancellation and stopping. The terminal debugger displays the code separately. Tools should use this structured field or Rust's Fault.code, not parse the formatted message.

.NET comparison

.NET exposes exception types and Exception.HResult for classification. StackOverflowException has a defined HRESULT and concerns CLR execution-stack exhaustion. neoCLR keeps a small terminal host outcome with a symbolic code. It supplies stable classification without a guest exception hierarchy, but has coarser categories and no HRESULT compatibility or catchable-fault semantics. The embedding process is not deliberately aborted by an ordinary neoCLR Fault.

String intern retention limits

Rust hosts configure Limits.intern_entries (default 4096) and Limits.intern_bytes (default 1 MiB). Each interpreter execution has its own strong intern pool, including an isolated worker execution. A new entry beyond either quota raises InternPoolLimitExceeded; looking up an existing value still succeeds at capacity. Empty text consumes an entry even though it consumes no payload bytes. These budgets count unique retained UTF-8 payload, not table capacity, Arc headers, allocator metadata, temporary input Strings or total process memory. Setting the entry quota to zero prevents all insertions. Limits are terminal runtime budgets, not recoverable Storage errors or guest-selected Fault codes. Use ..Limits::default() when a host does not need to override these budgets.

Shared host presentation

Rust FaultCode::standard_message(self) -> Optional<&'static str> returns the standard English runtime message for that code. It returns None for UserFault, whose message is supplied by the guest. Wording is diagnostic; use codes for machine decisions.

Fault::diagnostic(&self) -> FaultDiagnostic<'_> returns a borrowed, allocation-free host view with public fields code: FaultCode, message: &str, and stack_trace: Optional<&StackTrace>. The message follows the code rule above. An absent trace remains absent; frames are not fabricated for loader/host failures. Display prints code/message, then innermost-first method names and neoIL instruction indices, marking truncation. It does not terminate the host, capture argument/local values or run cleanup.

let diagnostic = fault.diagnostic();
eprint!("{diagnostic}");

Legacy Fault fields and Display remain compatible, including site-specific runtime messages. The common view is the backend-neutral presentation contract. Native AOT's experimental caller-owned equivalent and C renderer are documented in the fault capture experiment. Its text is image-owned; Rust's view borrows the Fault/trace. Neither lifetime implies guest-managed ownership. Standalone adapters exit 1 on an unhandled fault; embedding hosts choose their own recovery/exit policy. No stable native ABI or new guest exception API is introduced.

Experimental native text lifetime

The AOT Console experiment's optional integer formatting bindings export ABI v4 with a caller-owned context and text buffer. Its fault prefix remains the ABI v3 layout; status 5 denotes NativeMemoryLimitExceeded and uses the shared standard message. UserFault messages may point into the invocation buffer: render/read them before the next entry call or releasing that buffer. Frame names and runtime messages remain image-owned. Each concurrent invocation needs distinct context and buffer storage. This is an experimental C hosting contract, not a Raven guest API or stable native ABI. See the full contract and header.

The optional reference-arena profile uses the same ABI v4 context for bounded object storage. Status 6 denotes NullReference with the shared standard message; native field faults retain interpreter frame/instruction locations. Its objects and cycles expire on reset and cannot be exported through the Int32-only entry contract. It does not establish a stable object ABI or a general collection policy.

The same experimental arena also admits packed byte arrays. Status 7 denotes ArrayLimitExceeded (the POC limits one array to 65,536 bytes); status 8 denotes IndexOutOfRange. Negative lengths retain RuntimeError, null array access retains NullReference, and insufficient invocation storage retains NativeMemoryLimitExceeded. All use shared standard messages and managed instruction locations. These bounds are experimental admission/resource policy, not a new platform-wide array limit.