---
title: "18.2 Reading a diagnostic"
url: https://una-lang.org/en/learn/tools/reading-a-diagnostic/
release: v0.4.0
edition: "0.2"
---

# 18.2 Reading a diagnostic

## 18.2.1 What a diagnostic is

A **diagnostic** is una's report of one problem in your code. Think of a note from a building inspector: it names the rule that is broken by its number, says where, says what is wrong, and suggests how to fix it. A diagnostic has the same parts:

- a **code**, such as U5001, which names the kind of problem and never changes;
- a **severity**, which is always `error` in this release: una has no warnings to ignore;
- a **domain**, the part of the language the problem belongs to: `syntax`, `names`, `types`, `authority`, `security`, `verification`, `runtime`, `project` or `internal`;
- a **message**, one sentence for a person;
- a **primary place**, the exact span of code the problem is about, and sometimes **related places**, other spans that explain it;
- **repairs**, ranked from best to worst, each with an exact edit or only a description;
- for a proof, the **obligation** that failed and a **counterexample**.

## 18.2.2 Why diagnostics have codes and parts

Suppose a checker printed only `error: sale_price may return a value below cost`. A person can read it. A script that wants to know whether the problem is a proof or a typo has to guess from the words, and the guess breaks the day the words improve. An editor that wants to underline the right characters has to find them in the sentence. A person who wants to know how to fix it has to work it out alone.

So every part of a Una diagnostic is a separate field. The code tells a program what happened, and stays the same when the message improves. The places are numbers, not prose. The repairs are a list, and the exact ones carry their edit. The text for people and the JSON for programs are two renderings of one value, so both always say the same thing.

## 18.2.3 A typo the checker catches

The simplest diagnostics come from a typo. [Chapter 1](https://una-lang.org/en/learn/hello/your-first-program-hello-world/#if-una-check-finds-a-mistake) read one in three steps: what is wrong, where, and the repair. Here is another, in a program that prints one line, with `print` changed to `write`, which `Console` does not have:

```diff include="steps/06-hello..steps/13-typo:src/hello.una" title="src/hello.una"
--- a/src/hello.una
+++ b/src/hello.una
@@ -4,4 +4,4 @@
 pub main() -> Unit
   uses @console: Console[print]
 =
-  @console.print("The store is open")
+  @console.write("The store is open")
```

`una check .` reports:

```text include="steps/13-typo/expected/rendered.txt"
[U1001] Error: capability `Console` has no operation `write`
   ╭─[ src/hello.una:7:12 ]
   │
 7 │   @console.write("The store is open")
   │            ──┬──
   │              ╰──── capability `Console` has no operation `write`
   │
   │ Note: run `una explain U1001` for an explanation
───╯
```

The first line gives the code, U1001, and the message: `Console` has no operation `write`. Under it, `src/hello.una:7:12` is the file, the line and the column, the 12th character of line 7; lines and columns count from 1. The excerpt shows line 7 with its number on the left. The marks under it, `──┬──`, underline the exact span, `write`, and the line from `╰──` repeats the message next to it. This time there is no `Help` line: `write` is close to no operation of `Console`, so the checker has no repair to offer. The `Note` names the command that explains the code, and with no exact edit, there is no last line about `una fix`.

Read every diagnostic in that order: the message says what, the place says where, and the help, when there is one, says what to do. A diagnostic of the verifier has more parts, in the same order.

## 18.2.4 A sale price with one wrong word


A diagnostic that the verifier reports has the most parts. This step computes a sale price that must never fall below cost, from a price, a cost and a percent off. It has a requirement it is derived from ([chapter 5](https://una-lang.org/en/learn/contracts/requirements-rules-from-outside-the-code/#s5-5)), and a private function that reads a typed percent. The body has one wrong word: on line 24, on the path where the discount goes below cost, it returns `price` instead of `cost`.

```una include="steps/09-refuted/src/discount.una" title="steps/09-refuted/src/discount.una" caption="with one wrong word, on line 24"
module discount

requirement PRICING_1
  text "A sale price is never below what the store paid for the product"
  source human
  owner pricing
  status active

--- An amount of money in cents, never negative.
pub kind Cents = Int where it >= 0

--- A discount in percent, from 0 to 90.
pub kind Percent = Int in 0..90

--- Why a typed percent was rejected.
kind PercentError = NotANumber(raw: Text) | OutOfRange(value: Int)

--- The price after `off` percent, never below `cost`.
pub sale_price(price: Cents, cost: Cents, off: Percent) -> Cents
  ensures result >= cost
  derived from PRICING_1
=
  let discounted = price - price * off / 100
  if discounted < cost then price else discounted

--- A percent typed by a person, such as "30".
parse_percent(raw: Text) -> Percent
=
  let n = raw.trim.to_int()
    if none fail NotANumber(raw)
  if n < 0 or n > 90
    fail OutOfRange(value: n)
  else
    n

pub main() -> Unit
  uses @console: Console[print]
=
  let off = parse_percent(" 30")
    if error use 0
  let lamp = sale_price(1990, cost: 1200, off: off)
  let desk = sale_price(12900, cost: 11000, off: off)
  @console.print("LAMP-01 {lamp}, DESK-02 {desk}")

example "30 percent off a lamp"
  do sale_price(1990, cost: 1200, off: 30)
  expect result == 1393

example "a typed percent above 90 is OutOfRange"
  do parse_percent("95")
  expect fails OutOfRange
```

`una check .` reports:

```text include="steps/09-refuted/expected/rendered.txt"
[U5001] Error: postcondition of `sale_price` is refuted
    ╭─[ src/discount.una:24:29 ]
    │
 20 │   ensures result >= cost
    │           ───────┬──────
    │                  ╰──────── ensures clause
    │
 24 │   if discounted < cost then price else discounted
    │                             ──┬──
    │                               ╰──── postcondition of `sale_price` is refuted
    │
    │ Help 1: repair 1: add a guard or an arm so that the failing path returns a value for which `result >= cost` holds
    │
    │ Help 2: repair 2: adjust the `ensures` clause
    │
    │ Note 1: obligation ob-8a05af02a5f7 (postcondition) is refuted: result >= cost
    │
    │ Note 2: counterexample: cost = 1, off = 0, price = 0, result = 0
    │
    │ Note 3: run `una explain U5001` for an explanation
────╯
```

## 18.2.5 The parts of a diagnostic

### 18.2.5.1 The first line: code and message

`[U5001] Error:` is the code and the severity. U5001 means that the verifier found values for which a promise fails: the promise is **refuted**. The message names which promise: the postcondition, the `ensures` clause, of `sale_price`.

### 18.2.5.2 The places

The box under the first line shows the code around each place, with the file, line and column of the primary place at its top: `src/discount.una:24:29`. Each place has a mark, a line under the span, and a label at its end:

- the **related place**, `ensures clause`, on line 20, is the promise;
- the **primary place**, on line 24, is the value that breaks it: `price`.

### 18.2.5.3 Help lines: the repairs

`Help 1` and `Help 2` are the repairs, best first, each numbered `repair N`. A repair with an exact edit ends with `edit <place> to "<text>"`, as the receipt's did. These two have no edit: the right change depends on what the function is meant to do, which una cannot know.

### 18.2.5.4 Note lines: the obligation, the counterexample, the explanation

- `Note 1` is the **obligation**: its identifier, `ob-8a05af02a5f7`, its kind, `postcondition`, and its goal, `result >= cost`. [Section 18.3](https://una-lang.org/en/learn/tools/what-was-proven-obligations-contracts-and-traces/#s18-3) lists every obligation by that identifier.
- `Note 2` is the **counterexample**: one choice of values for which the goal is false.
- The last `Note` says where to read more: `una explain U5001`.

### 18.2.5.5 The last line: what `una fix` can apply

A diagnostic with an exact edit ends the output with a count, ``1 of 1 diagnostics have an edit that `una fix` applies``, as the receipt's did. The refuted proof has none, so there is no such line.

### 18.2.5.6 Reading it from the top

:::steps
1. **The first line.** U5001: the postcondition of `sale_price` is refuted.
2. **The two places.** The promise, line 20, and the value that breaks it, `price` on line 24.
3. **The repairs.** A guard or an arm that returns a value that keeps the promise, or a changed promise. Neither is mechanical.
4. **The obligation.** Its goal, `result >= cost`, is the promise with the returned value as `result`.
5. **The counterexample.** With `price = 0` and `cost = 1`, the discounted price 0 is below cost, so the function returns `price`, 0, and 0 is not at least 1. Plug the values into the code and the bug is in plain sight.
6. **The note.** Where to read more.
:::

## 18.2.6 Several problems in one check

`una check .` reports every problem it finds in one pass, not only the first, as the receipt of [Habits from other languages](https://una-lang.org/en/learn/tools/check-format-and-fix/#habits-from-other-languages) showed. With two misspelt operations in the program of [A typo the checker catches](#a-typo-the-checker-catches), it reports two diagnostics:

```diff include="steps/06-hello..steps/12-two-typos:src/hello.una" title="src/hello.una"
--- a/src/hello.una
+++ b/src/hello.una
@@ -4,4 +4,5 @@
 pub main() -> Unit
   uses @console: Console[print]
 =
-  @console.print("The store is open")
+  @console.write("The store is open")
+  @console.show("Orders placed before 18:00 ship today")
```

```text include="steps/12-two-typos/expected/diagnostics.txt"
error U1001 at src/hello.una:7:12: capability `Console` has no operation `write`
error U1001 at src/hello.una:8:12: capability `Console` has no operation `show`
```

This book lists them here in a short form, one line each: the code, the place and the message. In your terminal, `una check .` prints each one in full, as for `write`. Fix them in any order, and run `una check .` again until it prints nothing.

## 18.2.7 Repairs that cost a guarantee

Not every repair is equal. This step halves a price typed at the till, for a two-for-one offer, and promises a `Cents`, which is never negative:

```una include="steps/10-half-price/src/discount.una" title="steps/10-half-price/src/discount.una"
module discount

--- An amount of money in cents, never negative.
pub kind Cents = Int where it >= 0

--- Half of a price typed at the till, for a two-for-one offer.
half_price(typed: Int) -> Cents = typed / 2

pub main() -> Unit
  uses @console: Console[print]
=
  @console.print("{half_price(1990)}")
```

```text include="steps/10-half-price/expected/rendered.txt"
[U5001] Error: refinement `result >= 0` is refuted
   ╭─[ src/discount.una:7:35 ]
   │
 4 │ pub kind Cents = Int where it >= 0
   │                            ───┬───
   │                               ╰───── where clause
   │
 7 │ half_price(typed: Int) -> Cents = typed / 2
   │                                   ────┬────
   │                                       ╰────── refinement `result >= 0` is refuted
   │
   │ Help 1: repair 1: add a guard (`if` or a `when` arm) that handles the values where `result >= 0` does not hold
   │
   │ Help 2: repair 2 (escape: checked; a runtime test replaces the static proof: the program fails at run time where the proof would have rejected it; it counts against [escape_budget] and is listed in the build report): check the value with `checked(value, result >= 0) else fail <Variant>`
   │
   │ Note 1: obligation ob-5d6aa711c19b (refinement) is refuted: result >= 0
   │
   │ Note 2: counterexample: result = -1, typed = -2
   │
   │ Note 3: run `una explain U5001` for an explanation
───╯
```

The counterexample is a typed amount of -2, which halves to -1. The two repairs differ in what they cost:

- **Repair 1 keeps every guarantee.** A guard that handles a negative amount, and the verifier proves the result again.
- **Repair 2 is an escape.** `checked` tests the condition while the program runs instead of proving it ([chapter 7](https://una-lang.org/en/learn/failure/when-no-proof-can-decide-checked-and-opaque-predicates/#s7-5)). The program then fails at run time where the proof would have rejected it, it counts against the package's `[escape_budget]`, and the build report lists it. The label `(escape: checked; …)` says so, before the description.

Escapes always come after the repairs that keep the guarantee. A third kind of mark, `(widens authority: …)`, says that a repair gives a function more power than it had: [A capability that is not there](https://una-lang.org/en/learn/tools/common-mistakes/#a-capability-that-is-not-there-u3001) shows one. Widenings come after the repairs that keep authority, and `una fix` applies neither an escape nor a widening.

## 18.2.8 An explanation for every code: `una explain`

Every code has an explanation in the binary: a paragraph, and for almost every code a failing example and a fixed one. You need no network and no browser. The first lines of the one for the missing label of [section 18.1](https://una-lang.org/en/learn/tools/check-format-and-fix/#s18-1):

```text include="steps/01-fix/expected/commands/explain.txt#L1-L4"
$ una explain U2004
# U2004: Missing argument label

A call with two or more arguments may omit the label of its first argument only; every other argument names its parameter, as in `max(x, b: 10)`, or is a bare name equal to the parameter's name, which counts as labeled (`spec/04 §3`). A constructor with two or more fields labels every argument, the first included. The diagnostic carries an edit that labels the argument with the parameter at its position.
```

The paragraph is the full rule, and it may name terms and rules that this book does not cover; you do not need all of it to fix the problem. The failing example and the fixed one follow it. The site has the same text on each code's page, such as [U2004](https://una-lang.org/en/docs/errors/U2004/).

## 18.2.9 The same diagnostic as JSON

The refuted sale price, for a program, is one line of JSON:

```sh
una --json check .
```

```json include="steps/09-refuted/expected/commands/json.txt#L2"
{"schema":"una.diagnostics/1","diagnostics":[{"schema":"una.diagnostic/1","code":"U5001","severity":"error","domain":"verification","message":"postcondition of `sale_price` is refuted","primary":{"file":"src/discount.una","start":{"line":24,"col":29},"end":{"line":24,"col":34}},"related":[{"file":"src/discount.una","start":{"line":20,"col":11},"end":{"line":20,"col":25},"message":"ensures clause"}],"obligation":{"id":"ob-8a05af02a5f7","kind":"postcondition","goal":"result >= cost","status":"refuted"},"counterexample":{"bindings":[{"name":"cost","value":1},{"name":"off","value":0},{"name":"price","value":0},{"name":"result","value":0}]},"repairs":[{"rank":1,"escape_cost":0,"description":"add a guard or an arm so that the failing path returns a value for which `result >= cost` holds","edit":null},{"rank":2,"escape_cost":0,"description":"adjust the `ensures` clause","edit":null}],"explain":"una explain U5001"}],"fixable":0}
```

Every part of the text is a key:

| Key | What it holds |
| --- | --- |
| `code`, `severity`, `domain`, `message` | The first line, split into its parts |
| `primary`, `related` | The places, each a file, a `start` and an `end`, with a `message` for a related place |
| `obligation` | The identifier, kind, goal and status of the obligation, for a proof only |
| `counterexample` | The values, as a list of `bindings`, each a `name` and a `value`, for a proof only |
| `repairs` | Each repair's `rank`, its `escape_cost`, its `description` and its `edit`, or `null` when it has none |
| `explain` | The command that explains the code |
| `fixable` | At the end of the document: how many diagnostics `una fix` would repair |

The escape of the half price, in JSON, is a repair with `escape_cost` 1 and an `escape` key that says what the guarantee loses:

```json include="steps/10-half-price/expected/commands/json.txt#L2"
{"schema":"una.diagnostics/1","diagnostics":[{"schema":"una.diagnostic/1","code":"U5001","severity":"error","domain":"verification","message":"refinement `result >= 0` is refuted","primary":{"file":"src/discount.una","start":{"line":7,"col":35},"end":{"line":7,"col":44}},"related":[{"file":"src/discount.una","start":{"line":4,"col":28},"end":{"line":4,"col":35},"message":"where clause"}],"obligation":{"id":"ob-5d6aa711c19b","kind":"refinement","goal":"result >= 0","status":"refuted"},"counterexample":{"bindings":[{"name":"result","value":-1},{"name":"typed","value":-2}]},"repairs":[{"rank":1,"escape_cost":0,"description":"add a guard (`if` or a `when` arm) that handles the values where `result >= 0` does not hold","edit":null},{"rank":2,"escape_cost":1,"escape":{"kind":"checked","cost":"a runtime test replaces the static proof: the program fails at run time where the proof would have rejected it; it counts against [escape_budget] and is listed in the build report"},"description":"check the value with `checked(value, result >= 0) else fail <Variant>`","edit":null}],"explain":"una explain U5001"}],"fixable":0}
```

## 18.2.10 How diagnostics behave

- **Places count from 1.** Lines and columns start at 1, and a column counts characters: a character such as `é` counts as one column, even though a file stores it in more than one byte, a unit of storage. `end` is the first position after the span: the mark under `price` starts at column 29 and ends before column 34, five characters.
- **Proof parts only for proofs.** `obligation` and `counterexample` appear only for the verifier's codes, U5001 and U5002, the second for a goal the solver could not decide.
- **A counterexample is one case, not a run.** The solver picks values that break the goal, often the smallest ones. A record or a list it does not need in detail gets a placeholder name such as `Product#0` or `List#0`, and its fields that matter get their own lines, such as `product.cost = 1`.
- **Repairs are ordered.** By escape cost first, then by rank: the repairs that keep every guarantee come first, then those that widen, then the escapes.

## 18.2.11 Text or JSON

:::decide
**Which to use:**

| You are… | Read |
| --- | --- |
| A person at a terminal | The text: `una check .` |
| A script or a release check | The JSON, `una --json check .`, and the exit code |
| An editor | Neither: `una lsp`, tier 0 as you type, proofs on save |
| Unsure what a code means | `una explain <code>`, or its page on the site |
:::

## 18.2.12 Check yourself: reading a diagnostic

This step takes a coupon off a price, and promises a `Cents`:

```una include="steps/11-coupon/src/discount.una#after_coupon" title="steps/11-coupon/src/discount.una"
--- The price after a coupon worth `off` cents.
pub after_coupon(price: Cents, off: Cents) -> Cents = price - off
```

`una check .` rejects it with U5001. Before you look: which value of `off` breaks the promise when `price` is 0? And will `una fix .` change the code?

:::answer Show the answer
Any coupon worth more than the price, such as `off = 1` with `price = 0`:

```text include="steps/11-coupon/expected/rendered.txt"
[U5001] Error: refinement `result >= 0` is refuted
   ╭─[ src/discount.una:7:55 ]
   │
 4 │ pub kind Cents = Int where it >= 0
   │                            ───┬───
   │                               ╰───── where clause
   │
 7 │ pub after_coupon(price: Cents, off: Cents) -> Cents = price - off
   │                                                       ─────┬─────
   │                                                            ╰─────── refinement `result >= 0` is refuted
   │
   │ Help 1: repair 1: add a guard (`if` or a `when` arm) that handles the values where `result >= 0` does not hold
   │
   │ Help 2: repair 2 (escape: checked; a runtime test replaces the static proof: the program fails at run time where the proof would have rejected it; it counts against [escape_budget] and is listed in the build report): check the value with `checked(value, result >= 0) else fail <Variant>`
   │
   │ Note 1: obligation ob-5649fc082080 (refinement) is refuted: result >= 0
   │
   │ Note 2: counterexample: off = 1, price = 0, result = -1
   │
   │ Note 3: run `una explain U5001` for an explanation
───╯
```

`result = -1` breaks `result >= 0`, the rule of `Cents`. `una fix .` changes nothing: neither repair has an edit, and the second is an escape. The fix is a decision, such as returning 0 when the coupon is worth more than the price, or a `requires off <= price` that every caller proves.
:::

Second, the program of [A typo the checker catches](#a-typo-the-checker-catches), with one wrong letter order this time:

```diff include="steps/06-hello..steps/14-misspelt:src/hello.una" title="src/hello.una"
--- a/src/hello.una
+++ b/src/hello.una
@@ -4,4 +4,4 @@
 pub main() -> Unit
   uses @console: Console[print]
 =
-  @console.print("The store is open")
+  @console.pirnt("The store is open")
```

The checker reports U1001 at line 7, column 12, where `pirnt` starts, and suggests `print` as an exact edit. Before you look: in `una --json check .`, what is `fixable`, and what are the `start` and `end` of the repair's `edit`?

:::answer Show the answer
```json include="steps/14-misspelt/expected/commands/json.txt#L2"
{"schema":"una.diagnostics/1","diagnostics":[{"schema":"una.diagnostic/1","code":"U1001","severity":"error","domain":"names","message":"capability `Console` has no operation `pirnt`","primary":{"file":"src/hello.una","start":{"line":7,"col":12},"end":{"line":7,"col":17}},"related":[],"repairs":[{"rank":1,"escape_cost":0,"description":"write `print`","edit":{"file":"src/hello.una","start":{"line":7,"col":12},"end":{"line":7,"col":17},"replacement":"print"}}],"explain":"una explain U1001"}],"fixable":1}
```

`fixable` is 1: the one diagnostic has a repair with an edit. The edit starts at line 7, column 12, and ends at column 17, the first position after `pirnt`, so it covers the five characters of the word and replaces them with `"print"`. The `edit` has the same span as `primary`, since the repair rewrites exactly the marked word.
:::
