On this page
The checker validates names, types, and word connections across the whole program before execution. A static error means no prompt is written and no input is consumed. Runtime errors happen during execution and may follow earlier output.
Read a diagnostic
Text diagnostics start with file:line:column: message. The source line follows, with a caret under the failing expression. When the checker knows a concrete fix, it adds a hint: line.
bad.zhex:1:1: print does not support type Result<String, InputError>
print(read-line("Name: "))
^^^^^^^^^^^^^^^^^^^
hint: this value is a Result; add postfix try to unwrap it, as in text.to-int("N: ") try
Type errors may say where a value came from. This can point to the operation that produced an unexpected result. Hints describe a specific action only when the checker knows a fix.
The error catalog lists stable built-in diagnostic codes and their meanings. Codes supplied by error.new and error.wrap are application data and do not each have a catalog entry. On a language error, zhex run file.zhex --report=json emits a JSON object with code, severity, file, line, column, message, and hint. Checker diagnostics with an expression span can also include span_start_column and span_end_column; runtime diagnostics do not include these fields. A successful run emits no report.
Trace a run
Use --trace to see interpreter steps as JSON Lines on standard error:
zhex run examples/composition.zhex --trace
The event vocabulary is:
| Event | Data |
|---|---|
word-call |
Program word name, source file and line, and rendered arguments. Built-in calls do not emit this event. |
binding |
Name, rendered value, and source file and line. A result binding renders as ok("value") or err("message"). |
flow-step |
Word name, the value passed to it, and source file and line. |
word-return |
Program word name, returned value, and the word’s source file and line. |
Values use the checked type for rendering: integers as digits, booleans as true or false, strings verbatim, Unit as an empty string, buffers as buffer(n lines), and files as file("path"). Module word names are qualified. REPL traces use "file":"repl".
Tracing can be combined with --report=json: step events go to standard error before the final report. A trace write failure does not fail a run. Without --trace, normal program output is unchanged.
Inspect a returned error
An error bound by catch is an Error value for inspection. The built-in accessors are:
| Operation | Result |
|---|---|
error.code(Error) |
Stable error code as a String. |
error.message(Error) |
Human-readable message as a String. |
error.operation(Error) |
Operation that first produced the error. |
error.file(Error) |
Origin source filename. |
error.line(Error) / error.column(Error) |
Origin line and column as Ints. |
error.detail(Error, key) |
Documented detail value as a String, or "" if absent. |
error.has-cause(Error) |
Whether a wrapped cause exists. |
error.cause(Error) |
A result containing the cause, or error-no-cause. |
For example, a handler can branch on the stable code rather than message wording:
let value = text.to-int("bad") catch problem
print(error.code(problem))
print(error.operation(problem))
0
print(value)
Use error.detail for structured fields such as a failed file path and normalized reason (path, reason), a bad buffer index (index, length), an array coordinate (axis, index, extent), a wrong array rank (rank, expected_rank), a bad shape (axis, extent), an element limit (limit), or an out-of-range argument (index, argument-count). File open reasons are not-found, permission-denied, or other; read reasons are invalid-utf8, closed, read-failed, or end-of-file. Missing detail keys return the empty string. error.new(code, message) creates a cause-less application error at that call site. error.wrap(code, message, cause) converts an existing error to the common Error family while preserving its origin and cause. Use error.cause(problem) try when a cause is required, or catch error-no-cause when it is optional.
Error is the common built-in error type, not a user-defined record. Result error families remain InputError, ParseError, FileError, BufferError, and Error; when a word changes a concrete family to Error, the conversion through error.wrap is explicit.
Report handled and unhandled failures
An application may install a named reporter before its fallible calls:
word report(problem: Error) -> Unit
print(error.code(problem))
error.set-reporter(report)
The callback receives an Error. Call error.report(problem) in a catch body to report a failure the program handled. If a failure instead escapes the program, the runtime calls the reporter once before writing the normal diagnostic. Propagation through several try layers does not call it at each layer. Reporting the same occurrence explicitly and then allowing it to escape does not report that occurrence twice.
The reporter runs synchronously. Its failure cannot replace the original error, and reporting is suppressed while the callback itself runs. Nothing is sent to a network or external service by default; the program defines what the callback does. Error messages and details can include input or paths, so select and sanitize fields deliberately.