Errors & Diagnostics

Nuri distinguishes between fatal errors (returned as error) and non-fatal degradations (recorded as Diagnostic entries in the result). Fatal errors stop the highlighting call. Non-fatal degradations allow tokenization to continue for subsequent lines.

Sentinel errors

1
var (
2
    ErrLanguageNotFound = registry.ErrLanguageNotFound
3
    ErrThemeNotFound    = registry.ErrThemeNotFound
4
    ErrGrammarCycle     = grammar.ErrGrammarCycle
5
    ErrGrammarDepth     = grammar.ErrGrammarDepth
6
)

All four are wrapped with %w by the functions that return them. Use errors.Is to check:

1
if errors.Is(err, nuri.ErrThemeNotFound) {
2
    // theme name not in registry
3
}

`nuri.ErrLanguageNotFound`

The grammar name is not in the registry. In h.CodeToTokens() and h.CodeToHTML(), this triggers a plaintext fallback with a "unknown_lang" diagnostic rather than a hard error. Use errors.Is to promote it to a hard error when strict behavior is needed.

`nuri.ErrThemeNotFound`

The theme name is not in the registry. Returned by h.GetThemeColors() and by the internal theme resolver used by all highlighting methods.

`nuri.ErrGrammarCycle`

Grammar include resolution detected a cycle (e.g. grammar A includes grammar B, which includes grammar A). Returned during tokenization when the grammar dependency graph contains a loop.

`nuri.ErrGrammarDepth`

Grammar include resolution exceeded the depth limit. Returned when deeply nested grammar includes exceed the maximum allowed depth, even if no cycle exists.

Fatal vs non-fatal

Fatal errors are returned as the error value from highlighting methods:

WASM trap (runtime failure inside the Oniguruma module)
Context cancellation (ctx.Done() before or during tokenization)
Malformed grammar or theme JSON (from h.LoadLanguage() or h.LoadTheme())
Theme not found (from h.GetThemeColors())

Non-fatal degradations are recorded in TokensResult.Diagnostics. The highlighting call succeeds, and the affected line is emitted as a single unstyled token or with partial styling. Tokenization continues for subsequent lines.

Diagnostics

1
type Diagnostic struct {
2
    Line int    `json:"line"`
3
    Kind string `json:"kind"`
4
}

Line is 0-based.

Kind	Trigger	What happens
`"timeout"`	Line tokenization exceeded `TimeoutMs`	Partial tokens preserved; WASM instance replaced with a fresh one
`"too_long"`	Line byte length exceeded `MaxLineLength`	Single unstyled token emitted; no WASM call made
`"panic"`	Tokenizer panicked on a line	Instance marked poisoned and replaced
`"unknown_lang"`	Language name not found in registry	Entire input rendered as plaintext

Checking diagnostics

1
result, err := h.CodeToTokens(ctx, code, nuri.CodeToTokensOptions{
2
    Lang:  "go",
3
    Theme: "github-dark",
4
})
5
if err != nil {
6
    log.Fatal(err)
7
}
8
for _, d := range result.Diagnostics {
9
    log.Printf("line %d: %s", d.Line, d.Kind)
10
}

h.CodeToHTML() applies the same diagnostic model internally. The diagnostics are not directly accessible from the HTML output, but the affected lines appear as unstyled <span> elements in the rendered HTML.