---
title: "Diagnostics"
description: "Every diagnostic code a GistUI processor reports and every runtime error code, with severity, cause and effect."
---

> Documentation Index
> Fetch the complete documentation index at: https://gistui.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Diagnostics

A processor reports problems as **diagnostics**. A runtime reports problems as `error` actions. Codes are stable across versions; messages are for people and may change.

## The diagnostic object

```ts
{
  code: "invalid-enum",
  severity: "warning",       // "error" | "warning"
  stmt: "card",              // the statement concerned, when there is one
  line: 4,                   // 1-based
  fixed: true,               // the processor repaired it and the tree shows the repair
  message: "…",              // for people
  hint, use, prop, arg, ref, // optional details
}
```

Get them from `parse(source, library).errors`, from a renderer's `onError`, or from `validateProgram` on the server.

## Processor codes

| Code | Severity | Raised when | Effect |
|---|---|---|---|
| `prose-ignored` | warning | A line is not a statement, comment or fence | The line is ignored |
| `lenient-syntax` | warning | A recovery rule was applied | The text is read as the rule says; nothing is lost |
| `unterminated-string` | error, fixed | A string was still open at the line end | The string and the statement end there |
| `parse-failed` | error, fixed | A character was skipped, or text after the value was ignored | The statement is kept |
| `parse-failed` | error | The statement could not be read | The statement is dropped |
| `limit` | error | A processor limit was reached | See [limits](/docs/protocol/format/#limits) |
| `unsupported-version` | warning | The version pragma names an unknown major version | Processing continues |
| `reserved-id` | warning | A statement id is a flag name of the catalog | None; as a bare word the name means the flag |
| `unknown-component` | error, fixed | The name is not in the catalog and a close name was used | The closest component is used |
| `unknown-component` | error | The name is not in the catalog and nothing is close | An `#unknown` node |
| `unknown-prop` | warning | A named argument or patch names no prop | The argument is ignored |
| `missing-required` | error | A required prop has no value | The node is kept without the prop |
| `excess-args` | error, fixed | A positional argument has no place | The argument is ignored |
| `positional-optional` | warning | A prop that is not positional was passed by position | The prop is set |
| `invalid-prop` | warning | A value does not fit the prop type | The default, or no value |
| `invalid-enum` | warning, fixed | A value was corrected to a close enum value | The close value is used |
| `invalid-enum` | error | A value is not an enum value and nothing is close | The default, or no value |
| `invalid-child` | warning | A child is not accepted by its parent, or a data value is in child position | A component child is kept; a data value is dropped |
| `bare-text` | warning | A bare word that nothing defines was used as text | The word is the text |
| `blocked-url` | warning, fixed | A URL that loads by itself is refused | The URL is removed |
| `unresolved-ref` | error, fixed | A reference to an id that nothing defines | The reference is dropped |
| `cycle` | error, fixed | A statement contains itself | The reference that closes the loop is dropped |
| `patch-target-missing` | error | A patch or append has no valid target | The edit is ignored |
| `no-root` | warning, fixed | No statement `root`; the first component is used | That component is the root |
| `no-root` | error | There is no root | The tree is empty |
| `unreachable` | warning | A statement is not used | None |

## Runtime error codes

Reported to `onAction` as `{ type: "error", code, … }`.

| Code | Raised when | Effect |
|---|---|---|
| `tool-not-found` | A query or mutation names a tool that is not in its set | The call fails |
| `tool-failed` | A tool call failed, was refused by the host, or passed the call budget | The call fails; a mutation stops its action list |
| `blocked-url` | `@open` was refused, or a URL that loads by itself was refused at run time | The action list stops, or the URL is removed |
| `unknown-step` | An action step is not known | The action list stops |
| `limit` | A runtime limit was reached | See [limits](/docs/protocol/format/#limits) |

## Validity

```ts
const r = parse(source, library);
r.valid.strict;  // no diagnostics at all
r.valid.lenient; // everything that was wrong was repaired by a rule
```

A good generator produces strict programs. A good host accepts lenient ones.

## Sending errors back to a model

For a model-assisted repair, send only the failing statements and their diagnostics: [Autofix and repair](/docs/guides/autofix/#asking-the-model-to-fix-the-rest).

Source: https://gistui.com/docs/reference/diagnostics/index.mdx