Error reference #
46 error codes in three namespaces: 11 raised by the
engine itself, 33 declared by individual grammar
plugins, and 4 returned by the C shared libraries. A
tabnas diagnostic always carries a code, and the code — never
the message text — is what stays the same across the TypeScript and Go
runtimes. Match on it.
Generated from the engine's schema/error-codes.json
and from each plugin's tabnas.plugin.json descriptor —
nothing on this page is hand-listed. Engine 0.8.10.
Machine-readable: /versions.json.
Engine codes #
Raised by the parsing engine itself, so any grammar can produce them.
{placeholders} in a message are filled from the failing
token and its details.
| Code | Message |
|---|---|
cancel | parse cancelled |
end_of_source | unexpected end of source |
internal Go only | internal error: {src} |
invalid_ascii | invalid ascii escape: {src} |
invalid_unicode | invalid unicode escape: {src} |
unexpected | unexpected character(s): {src} |
unknown | unknown error: {code} |
unknown_rule | unknown rule: {rulename} |
unprintable | unprintable character: {src} |
unterminated_comment | unterminated comment: {src} |
unterminated_string | unterminated string: {src} |
Plugin codes #
Declared by one grammar plugin, in its own error catalogue. A plugin raises these in addition to the engine codes above.
C ABI codes #
A different namespace, and worth reading as one. These are not parse
diagnostics: they come back in the JSON reply of a libtabnas<format> shared library, and they describe
the call — a bad pointer, a handle you already freed — rather
than the input you passed. All 19 libraries return the same four, because the ABI
is uniform by decision
(v1).
The distinction that actually costs people time: a library returns {"ok":true,"accept":false} when your input is outside
the format. That is an answer, not an error, and it
carries no code from this table. A code from this table means the call
itself was wrong.
Reading a diagnostic #
Every failing parse produces the same structured object — the same
fields in both runtimes, described by the engine's diagnostic.schema.json. The fields worth reading
first are code (what went wrong), row/col (where), expected (which
tokens would have matched) and ruleStack (how the parser
got there).
The agents guide covers using these while
iterating on a grammar, and the debug-parse skill is the same
workflow packaged for an agent.