Diagnostics
Every error,
by name.
Each diagnostic carries a stable code. The first line is always file:line:column: message; the source excerpt, caret, and hint: are additive detail.
Machine readers: zhex run file.zhex --report=json emits {code, severity, file, line, column, message, hint}, plus optional span_start_column/span_end_column for checker diagnostics with a span. The contract lives in docs/diagnostics-plan.md.
The catalog
What it means, how to fix it.
Codes are stable: never renamed, never reused. The catalog comes from the interpreter's own definitions.
list-range
The list index is negative or outside its current length. Use a valid zero-based index.
collection-limit
A list or array would exceed the runtime limit of 1,000,000 elements. Reduce its size.
collection-iterating
An active iteration prevents mutation of the traversed collection. Mutate a different collection or wait until traversal finishes.
console-exit-status
console.exit requires a status from 0 through 255. Choose a portable exit status in that range.
unhandled-result
Handle or propagate each Result with catch or try. An immutable stored Result must be handled by the immediately following statement in the same block.
error-no-cause
error.cause was called for an Error without a cause. Check error.has-cause first or handle the Result.
source-utf8
The file is not valid UTF-8. Re-save it as UTF-8; Zhex source has no other encoding.
tab-character
A tab appeared outside a string. Indentation is four spaces per level; replace tabs with spaces.
indentation
A line's indent is not a multiple of four spaces, or it opens more than one level at once. Each block indents exactly four spaces from its parent.
unterminated-string
A string literal has no closing quote before the end of the line. Close it on the same line; strings do not continue across newlines.
string-escape
A string contains an escape Zhex does not support, or invalid UTF-8. Strings are double-quoted and use Go-style escapes like \n and \".
unexpected-character
A character cannot start any token. Check for stray punctuation or a non-ASCII symbol; names are ASCII letters, digits, underscores, and hyphenated segments.
expected-token
The parser expected a specific token and found something else. The message names both; fix the line to match the expected grammar.
expected-name
A keyword appears where a name is required. word, let, var, if, and the other keywords are reserved; choose a name that is not one of them.
unknown-type
A type name is not one of Int, Bool, String, Unit, Buffer, or File. Check the spelling; there are no user-defined types yet.
expected-indent
A construct needs an indented block on the following lines. Indent the body four spaces. Open (), [], and {} delimiters can continue expressions across lines, but do not replace a required block body.
empty-block
A block header is followed by nothing. Every block needs at least one statement.
nesting-limit
Expressions or blocks nest past the parser's limit. Split the expression into named parts with let.
integer-literal-range
An integer literal is outside the signed 128-bit range. Keep literals within ±170141183460469231731687303715884105727; compute larger values at runtime.
expected-expression
A token cannot start an expression where one is required.
flow-step
A flow block needs at least one step word. Write one word per line; the first receives the seed value.
with-location
A with line did not directly follow the expression line it continues. Put with on the next line below the seed expression, at the same indentation, with no blank line between.
with-seed
A with block's seed produces Unit, so no step can receive it. Give with a value-producing expression line.
with-step
A with step name resolved neither through the block's namespace nor as a word in scope. Spell the step as a qualified name, or define the word it names.
unknown-name
No binding or word has this name. The hint suggests the closest known one; if the name contains a hyphen, that hyphen is part of the name — subtraction is written a - b with spaces.
duplicate-name
This name is already defined in the same scope. Choose a fresh name; shadowing is not allowed.
duplicate-word
A word with this name already exists, or it collides with a host word. Rename one of them.
word-result
The word's final statement produces a different type than its declared result. Make the last statement's type match the signature, or fix the signature.
immutable-name
A name defined with let cannot be reassigned. Declare it with var to allow updates.
assignment-type
A binding annotation must match its value's type.
The new value's type differs from the variable's type. There are no implicit conversions; convert explicitly (for example int.to-string).
When the checker can trace the value to the word that produced it, the message says where it comes from.
condition-type
An if condition must be Bool. Comparisons return Bool; integers and strings do not.
When the checker can trace the value to the word that produced it, the message says where it comes from.
branch-type
The branches of an if end in different types. Make every branch produce the same type.
range-type
The bounds of range(start, end) must both be Int; the path of file.stream(path) must be String.
try-input
Postfix try and catch need a Result value to unwrap. Results come from fallible words and operations. Inside a word, propagation requires a declared Result with the same error type.
unary-type
The unary operator (-, not) received the wrong type. - needs Int; not needs Bool.
When the checker can trace the value to the word that produced it, the message says where it comes from.
operand-types
A binary operator got two different operand types. If one side is a Result, add postfix try to unwrap it.
When the checker can trace the value to the word that produced it, the message says where it comes from.
bool-operand
and/or need Bool on both sides. Comparisons produce Bool; integers do not.
When the checker can trace the value to the word that produced it, the message says where it comes from.
compare-type
Equality comparison needs matching Int, Bool, or String values. If one side is a Result, add postfix try to unwrap it.
When the checker can trace the value to the word that produced it, the message says where it comes from.
ordering-type
Ordering comparison (< <= > >=) needs Int operands.
When the checker can trace the value to the word that produced it, the message says where it comes from.
addition-type
+ adds two Ints, concatenates two Strings, or concatenates a String and an Int — the string-context Int exception. Other equal operand types, such as two Bools, cannot use +; convert explicitly.
When the checker can trace the value to the word that produced it, the message says where it comes from.
arithmetic-type
- * / % need Int operands.
When the checker can trace the value to the word that produced it, the message says where it comes from.
argument-count
A word call passed the wrong number of arguments. The message states how many the word takes.
argument-type
An argument's type does not match the parameter. There are no implicit conversions; convert at the call site. When the checker can trace the value to the word that produced it, the message says where it comes from.
unknown-word
No word with this name exists. The hint suggests the closest known word; check the spelling or define it.
print-type
print accepts one Int, String, or Bool value. If it received a Result, add postfix try to unwrap it.
When the checker can trace the value to the word that produced it, the message says where it comes from.
range-context
range and file.stream exist only inside a for loop header — for n in range(start, end) and for line in file.stream(path). They cannot be called elsewhere.
main-parameters
A file whose top level has no statements names word main as its entry point, and zhex run and zhex compile call it with no arguments. Remove the parameter list from word main, or rename the word. Beside top-level statements, in an imported file, and in the REPL, main is an ordinary word name.
use-missing
A use names a module that could not be loaded. The message names the module and the searched path — the sibling <name>.zhex next to the importing file. Create that file or fix the module name in the use.
use-cycle
Modules import each other in a circle; the message spells the files in the cycle. A circle has no first file to check, so one use in the cycle must be removed.
use-reserved
A module is named text, int, buffer, file, or console. Those prefixes belong to the standard operations, so a module cannot take any of them. Rename the module file.
use-location
A use appears inside a word body or another block. use is a top-level statement; move it to the top level of the file.
module-body
An imported file contains top-level statements. Imported files declare words only; move the statements into the file you run — a zero-argument word main there is invoked as the entry point.
private-use
A word or record type beginning with an underscore is private to its module. Public declarations cannot expose a private record type. Make the declaration private or use a public type.
integer-overflow
An arithmetic result does not fit in a signed 128-bit integer. Overflow is an error in Zhex, not a wraparound; keep intermediate values in range.
division-zero
Division or remainder by zero. Guard the divisor with a condition first.
depth-limit
Word recursion passed the runtime depth limit of 256. Rewrite the recursion as a loop with var and for; loops have no depth limit.
unsupported-code
An internal invariant failed: the checker approved something the evaluator cannot run. This is a bug in Zhex, not in your program — please report the program that triggered it.
console-output
Writing to the output stream failed. Check that the output is writable (closed pipes fail this way).
console-input
Reading a line from the input stream failed, usually because the input ended. The reason detail is end-of-file when the input ended (Ctrl-D or piped EOF; an empty line is a success, not this error) and read-failed for a read failure; read it with error.detail to tell them apart. The failure propagates through try and exits the program; check that input is available.
console-utf8
The line read from the input stream is not valid UTF-8. Zhex reads UTF-8 text; supply the input as UTF-8.
text-to-int
The text given to text.to-int is not a signed 128-bit decimal integer. It accepts only digits, with an optional sign; surrounding whitespace is ignored.
replace-empty
text.replace was called with an empty old text. Every position matches an empty string, so there is no sane result; this is a bug signal, not a recoverable case. Pass a nonempty old text.
text-code-point
text.from-code-points received a code point that is not valid Unicode: negative, above U+10FFFF, or a surrogate half (U+D800..U+DFFF). Strings are UTF-8 text, so those values have no encoding; this is a bug signal, not a recoverable case. Check the numbers before building the list.
buffer-range
buffer.line or buffer.set-line received an index outside the buffer's lines. The failure lives inside the Result and surfaces through try; check the index against buffer.line-count first.
file-open
file.open, file.read, or a file.stream loop could not open the path. The message names the path and the operating system's reason; check the path and its permissions.
file-read
A read from an open file failed: the stream was drained ("end of file") or the file was closed. file.read-line at end of file fails inside the Result; to read a whole file, prefer file.read(path) or for line in file.stream(path).
file-utf8
A file's content is not valid UTF-8. Zhex reads UTF-8 text only; re-save the file as UTF-8.
file-write
file.write could not open, write, or close the path; the message names the path, the failing phase, and the operating system's reason. The failure lives inside the Result and surfaces through try; a failed write may leave a partial or truncated file, and a missing parent directory is never created.
file-exists
file.exists could not answer for the path: the message names the path and the operating system's reason, and the failure carries the not-found/permission-denied/other taxonomy in its details. A missing path is not this failure — it is the answer false; apply try or catch to inspect the checked form's failures.
file-list
file.list could not list the folder: the folder is missing, or the process may not read it, or the path is a file. The message names the folder and the operating system's reason; the failure lives inside the Result and surfaces through try.
file-size
file.size could not get the size of the path: it is missing, or the process may not stat it. The message names the path and the operating system's reason; the failure lives inside the Result and surfaces through try.
file-free-space
file.free-space could not report the bytes available on the volume containing the path: the path does not exist, or the platform cannot answer for it. The message names the path and the reason; the failure lives inside the Result and surfaces through try.
file-make-folder
file.make-folder could not create the folder: a parent is missing (pass parents: true to create ancestors), or the target already exists (the default one-level form refuses it; parents: true tolerates an existing folder), or the process may not write the parent. The message names the path and the operating system's reason; the failure lives inside the Result and surfaces through try.
file-delete
file.delete could not delete the path: it is missing, it is a nonempty folder (the safety default removes a file or an empty folder only; file.delete-folder(recursive: true) removes a tree), or the process may not remove it. The message names the path and the operating system's reason; the failure lives inside the Result and surfaces through try.
file-delete-folder
file.delete-folder could not remove the folder: it holds entries while recursive is false (the default removes an empty folder only; pass recursive: true for the whole tree), or the process may not remove something inside it. Recursive removal is best-effort: part of the tree may already be gone when the first failure is reported, and earlier effects stand. The message names the folder and the operating system's reason; the failure lives inside the Result and surfaces through try.
file-move
file.move could not rename the source to the target: the source is missing, the target exists (pass overwrite: true to replace an existing file), the target is a folder (never replaced in either mode), the two paths are on different devices (no copy fallback), or the process may not rename. The check-then-act window between the target check and the rename is inherent: a target that appears in between is left to the rename itself. The message names both paths and the reason; the failure lives inside the Result and surfaces through try.
env-read
env.load could not read the file: it is missing, or the process may not read it. The message names the path and the operating system's reason; the failure lives inside the Result and surfaces through try.
env-parse
A line of the file given to env.load is not a KEY=VALUE assignment: the = is missing, the key is empty, or the key contains spaces. The message names the line number and the offending text. Lines before the malformed one are already applied and stay applied — env.load never overrides, so rerunning after fixing the file keeps the earlier values.
argument-missing
console.arg received an index outside the program's command-line arguments. The message names the index and how many arguments were given; the failure lives inside the Result and surfaces through try. Check the index against console.args-count().
array-range
An array coordinate is outside its dimension.
array-rank
An array shape or index has the wrong rank.
array-shape
An array extent is negative.
json-syntax
JSON text is invalid or contains more than one value. Correct the input syntax.
json-type
A JSON value does not match the expected Zhex type. Inspect the path and correct the value.
json-field
A JSON object has an unknown, duplicate, or missing required field. Inspect the path and reason.
json-range
A JSON integer or collection exceeds the supported range. Correct the value or reduce the list size.
json-depth
JSON nesting exceeds the supported depth of 256. Reduce the nesting.
xml-syntax
XML text is invalid, carries a DTD or entity declaration, uses an undefined entity, or has more than one root element. Correct the input syntax.
xml-type
An XML element or attribute does not match the expected Zhex type, or mixes text with child elements. Inspect the path and correct the value.
xml-field
An XML element or attribute name is unknown, duplicated, missing, collides with its counterpart, or is namespace-qualified. Inspect the path and reason.
xml-range
An XML integer or document exceeds the supported range. Correct the value or reduce the element count.
xml-depth
XML nesting exceeds the supported depth of 256. Reduce the nesting.
date-parse
A date string is invalid. Use a Gregorian date in YYYY-MM-DD form.
time-parse
A time string is invalid. Use HH:MM:SS, optionally followed by fractional seconds.
duration-parse
A duration string is invalid or outside the supported nanosecond range.
temporal-invalid
Numeric date or time components are outside their valid range.
temporal-range
Temporal arithmetic produced a value outside the supported range.
instant-parse
An instant string is invalid. Include a date, time, and explicit RFC 3339 offset.
timezone-load
A named time zone is invalid or unavailable. Use UTC or an IANA time zone name.
unclosed-delimiter
An opening parenthesis, bracket, or brace has no matching closing delimiter.
doctest-mismatch
A ## > example in a word's doc produced a different value than the expected output lines after it (they run until a blank doc line or the next ## > line). Update the expected output, or fix the word. Checked by zhex doctests <file>; zhex run never executes docs.
doctest-check
A ## > example's expression failed to check or evaluate by itself. Fix the expression so it checks and evaluates — a naked fallible call needs try, and a Result cannot be echoed bare.
test-failed
A .test.zhex file run by zhex test exited nonzero without a diagnostic of its own — a failed test.check label, a deliberate exit, or a crash. Run zhex run <file> to see the failing check in place.
not-available-in-build
The build that ran the program does not provide this construct. zhex compile fences constructs its emitter does not support yet; the browser engine build has no filesystem or console arguments (file.* filesystem words, file.stream, console.arg, env.load). Run the program with zhex run, or rewrite it with constructs the build supports.