Errors reference

Rendered from docs/reference-errors.md in the engine repository, where a correction belongs, and where the test suite executes every example on this page.

Every refusal the engine can make carries a code, and every code carries a class. The code names the condition that was refused; the class says what kind of thing went wrong, and so which repair applies.

This page is normative for the registry: every registered code, its class, and the version it was first registered at. It is not normative for the report a code arrives in, nor for the failures themselves. aontu vet specifies the report: the fields a finding carries, what a site names, and the --format json object each verb answers. The language reference specifies each construct where that construct belongs, and states what refuses it there: see Errors for the message families, Exact or refused: lossy literals and The exactness budget for the numeric rules, and Errors under The constraint algebra for a constraint violation.

aontu explain answers one code from the same table a finding carries, and aontu help codes prints the agent-facing card of the classes, which is shorter than the table below and carries no counts.

Contents#

• Classes
• Dynamic-prefix families
• The registry in a finding
• Exit codes
• The codes
  • Class parse
  • Class conflict
  • Class incomplete
  • Class reference
  • Class compat
  • Class budget
  • Class internal
• Related

Classes#

There are seven classes, and the registry holds 172 codes across them.

A class states which repair applies rather than where in the engine the failure arose. aontu explain answers one code with its class and the engine’s own text for it.

Two conflict codes are reported after unification rather than by it: relation_cycle and relation_inverse_missing, whose shape and timing are under aontu relations.

Dynamic-prefix families#

Five registry rows are prefixes rather than whole codes: func:, op:, op[, ref[, and var[. The engine appends a name or a value, so a reported code may be func:upper or ref[$.x]. The bare func, op, ref, and var are separate rows with their own classes, and are not the same codes as the families.

Class lookup takes the exact registry entry first, then the registered prefix the code extends, and then internal, because an unregistered code is an engine defect rather than a user error. Hint lookup has no such fallback. It is exact, so a finding whose code extends a family carries no hint text although the prefix row has some, and aontu explain is the only place a prefix’s text is answered. func:upper is not a registry row, and resolves through func::

$ aontu explain func:upper
code:  func:upper
class: conflict

Function error:

Both the class and the text are the prefix’s. A finding carrying that code would take the class and carry no hint key.

The registry in a finding#

Three of a finding’s fields are read from the registry, and each carries a qualification the registry alone does not show.

Class. A finding’s class is the registered class, on every surface that reports one. A finding that mints its own code takes the class that code is registered with; a finding that repeats a code the engine raised takes the class from the same row, never one of its own. message is the code’s one-line headline throughout; the wording of that line is each implementation’s own, since the shared suite holds codes and classes rather than prose.

Hint text. All 172 codes have hint text. aontu explain --list prints them one per line, with each code’s class beside it; a code carrying no text would be marked (no text), and none is. A finding carries that text under hint when it repeats a code the engine raised and the run asked for --format json: vet, allow, model get, model why, view, the library’s diff (TypeScript, and no CLI verb of its own), and the MCP tools. A finding the report mints for itself carries its own message and no hint, and so does the bare command that evaluates a document. No text format prints hint text at all: aontu explain is the verb that answers one code’s.

Severity. The field’s domain is error, warning, and info, and nothing in either implementation reports info. Five codes are always reported at warning: deprecated, pref_not_instance, patch_not_editable, patch_ambiguous, and patch_span_mismatch. Under aontu breaking with --allow-deprecated-removal, any error finding at a path the prior version marked with deprecate is reported at warning instead, so a compat code otherwise reported at error arrives at warning there.

Class incomplete is the only class a verdict rule reads. Under vet a schema that does not stand up on its own is verdict error whatever the finding’s class; otherwise any error outside class incomplete makes the verdict invalid, errors only of class incomplete make it incomplete unless --partial was passed, and a warning never moves it.

Exit codes#

A code’s class does not determine the exit code. scalar_value, class conflict, exits 1 where the contradiction is between schema and data, and 4 where it is inside the schema. Which values a verb answers, and what each one means for that verb, is in the API reference beside that verb’s option list. aontu vet, aontu subsume, aontu breaking, aontu view, aontu model set, and aontu fmt each state their own table.

aontu view is the one verb whose refusals split across two exits. Nine view_* codes are usage rather than the document’s fault and exit 2: view_kind_unknown, view_profile_unknown, view_rows_exceeded, view_at_required, view_sets_required, view_group_required, view_document_shape, view_style_profile, and view_style_unknown. A view kind that names no kind at all is caught while the arguments are being read, so it exits 2 with no report at all.

The codes#

The registry is test/spec/errcodes.tsv, which both implementations run as part of the shared suite; the parity it holds them to is stated under aontu explain.

The tables below are that file, one section per class, alphabetical within each. A since column is the version line at which the code was first registered, and 0.51.0 is the registry’s own inception version, so every code older than the registry carries it. Codes are append-only: a registered code is never renamed or reused, so a row stays registered after the condition it named stops arising. The parenthetical link on a row is the section that specifies the refusal; twenty rows have no such section and carry no link.

Class parse#

Class conflict#

Class incomplete#

Class reference#

Class compat#

Class budget#

Class internal#

Related#

• aontu vet for the report these findings arrive in, the fields they carry, and its own exit table.
• aontu explain for the verb that answers one code, and for what --list prints.
• Errors in the language reference for the message families and the rules that refuse a document.
• Read a conflict error for reading a two-site conflict message operand by operand.
• Collect errors instead of throwing for gathering every finding in one pass from the embedded API.
• test/spec/errcodes.tsv for the registry itself, which both implementations run.