---
title: "13.1 Diagnostic model"
url: https://una-lang.org/en/docs/spec/13-diagnostics-and-abi/1-diagnostic-model/
release: v0.4.0
source: https://github.com/una-lang/una/blob/v0.4.0/docs/spec/13-diagnostics-and-abi.md
---

# 13.1 Diagnostic model

Every problem the toolchain reports is a diagnostic with a registered code (§4). Human output (default) and JSON output (`--json`) are two renderings of the same value.

```json
{
  "schema": "una.diagnostic/1",
  "code": "U5001",
  "severity": "error",
  "domain": "verification",
  "message": "postcondition of availability is refuted",
  "primary": { "file": "src/events/seating.una", "start": { "line": 27, "col": 18 }, "end": { "line": 27, "col": 21 } },
  "related": [
    { "file": "src/events/seating.una", "start": { "line": 23, "col": 11 }, "end": { "line": 23, "col": 52 }, "message": "ensures clause" }
  ],
  "obligation": { "id": "ob-3f09a1c2e7b4", "kind": "postcondition", "goal": "e.remaining < 1 implies result is SoldOut", "status": "refuted" },
  "counterexample": { "bindings": [ { "name": "e.remaining", "value": 0 }, { "name": "result", "value": "Few" } ] },
  "repairs": [
    { "rank": 1, "escape_cost": 0, "description": "add the arm 'in 0..0 -> SoldOut' before 'in 0..<20' or adjust the ensures clause", "edit": null }
  ],
  "explain": "una explain U5001"
}
```

| Field | Rule |
| --- | --- |
| `severity` | `error`, `warning` or `note`. v0.1 defines errors only. |
| `domain` | `syntax`, `names`, `types`, `authority`, `security`, `verification`, `runtime`, `project`, `internal` |
| `primary` | Required. A diagnostic about something that has no position in any file is located at the empty range at line 1, column 1 of the file that declares what is checked: the package's `una.toml`, or the checked file itself for a package of one file (ADR 0022). A missing `verification.lock` is thus U7004 at `una.toml` 1:1 |
| `file` | Relative to the package root, with `/` separators. A file checked on its own, such as a single-module conformance case, has its directory as package root, so `file` is its bare name (ADR 0015) |
| Positions | 1-based line, 1-based column counted in Unicode scalar values after decoding; `end` is exclusive. Each maximal ill-formed subsequence of invalid UTF-8 counts as one column (Unicode §3.9); a byte order mark and a tab count as one column each (ADR 0015) |
| `obligation`, `counterexample` | Present only for U5001 and U5002 |
| Counterexample binding | `{ "name", "value" }`, and (v0.2, ADR 0078) `"label"`, as `"secret"` or `"secret[PII]"`, when the label of the name's declared type is above `public` (`spec/11 §5`). The key is omitted for a public binding; it is additive, and the schema stays `una.diagnostic/1`. The human output prints the bindings without their labels |
| Counterexample `unavailable` | (ADR 0101.) Present only when the solver refuted the obligation but gave no values for its model: the solver's message, and `bindings` is then empty. The obligation stays refuted. The key is omitted otherwise; it is additive, and the schema stays `una.diagnostic/1`. The human output prints the fixed note `counterexample: not available (the solver gave no values for the model)`, with no part of the message, which names internal symbols and positions of the generated query (#855) |
| `repairs` | Zero or more candidates, sorted by `escape_cost`, then `rank`. (ADR 0095.) `rank` is the position in that order, 1 to n without gaps. (ADR 0097.) Among repairs of equal `escape_cost`, those that widen come after the others |
| `escape` | (ADR 0095.) Present exactly when `escape_cost` is above 0, after `escape_cost`: `{ "kind", "cost" }`, where `kind` is `checked`, `escape_budget` or `trusted` (§3) and `cost` is one sentence that says what the guarantee loses. It is additive, and the schema stays `una.diagnostic/1`. The human output prints a repair as `repair N: ...`, or `repair N (escape: <kind>; <cost>): ...` |
| `widens` | (ADR 0097.) Present exactly when the repair widens, after `escape` when both are present: `{ "kind", "cost" }`, where `kind` is `authority`, `visibility` or `grant` (§3) and `cost` is one sentence that says what the widening costs. A widening keeps `escape_cost` 0. It is additive, and the schema stays `una.diagnostic/1`. The human output prints such a repair as `repair N (widens <kind>: <cost>): ...` |
| `edit` | `null`, or `{ "file", "start", "end", "replacement" }` when the repair is mechanical |

Diagnostics are sorted by file, start position, then code. Output is deterministic.

With `--json`, `una check` and `una fmt --check` print their diagnostics as one JSON object on stdout, followed by a newline (ADR 0012):

```json
{ "schema": "una.diagnostics/1", "diagnostics": [], "fixable": 0 }
```

`diagnostics` holds the diagnostics in the order above, each with its own `"schema": "una.diagnostic/1"` field; a new version of the diagnostic shape also bumps the list version. The array is empty when there are no diagnostics, and exit codes do not depend on `--json` (§5). Whitespace is not significant; the reference implementation prints compact JSON with object keys in the order shown in this section.

(ADR 0096.) `fixable` counts the diagnostics whose first repair `una fix` applies (§5): its `edit` is not `null`, its `escape_cost` is 0, it widens nothing, and it edits a module of the package. A U7001 with an edit counts too, since `una fix`'s format step applies it. The count is of the first round only: a file that parses after it reports its later phases. The key was added without a version change (ADR 0076 rule 1). In human mode, when the count is above 0, the last line on stderr is ``<n> of <m> diagnostics have an edit that `una fix` applies (`una fix --dry-run` lists them)``.
