Troubleshooting
What a refusal means and what to do about it.
When this product says no, it says no with a refusal class — a short, stable, hyphenated name such as egress-port-not-allowed or actor-near-miss. The class is the thing to search for. It is chosen deliberately, it does not change when the wording around it changes, and it is the one part of a refusal worth copying into a search box.
There are 191 declared refusal classes in this release, and this section carries all of them. saphan refusal-class status lists the same set for the build you have installed.
⚠ Some refusals carry an identifier that is not one of these declared classes — egress control's run refusals are the main example. Those are documented beside the act they belong to; see When something is refused.
How to read a refusal
- Find the class. It is the hyphenated token in the message; with
--json, it is theclassfield of the refusal payload. A client's error string is often generic, and several different judgements can produce the same sentence, so trust the class over the prose around it. - Look it up. Every refusal class, A to Z lists all 191 with the family page that covers each one.
- Read what the refusal itself printed before you change anything. Many refusals in this product are self-diagnosing: they print the exact argument to re-run with, or a literal command to fix custody, or the next act the record allows. Following the printed instruction is usually the whole fix, and guessing past it is how a small problem becomes a signed mistake.
- A refusal normally means nothing was written. A refused act does not half-apply, and you can re-run once you have changed the thing that was refused. The few exceptions say so on their family page — for example a signature file that is kept on purpose, a restore that is written and then rolled back, or a pull-request merge that stopped part-way through.
⚠ A refusal is not a crash. Every declared class is a decision the product made on purpose. If you are holding a class name, you are holding evidence that a check ran and answered — not evidence that something broke.
What this section can and cannot tell you
We would rather leave a page honest than fill it. So each class here is in one of two states:
- explained — this section says what it means, what caused it, and what to do. 46 classes are in this state.
- named only — this section confirms the class exists and what its name indicates, and says plainly that the resolution is not written down yet. 145 classes are in this state, and they are collected on the last page of this section.
⛔ We do not publish a remedy we cannot support. A wrong instruction on a page like this sends you to do something harmful, so an unwritten answer is preferred to an invented one. If you need one of the 145, ask us — that request is what moves a class from the second list to the first.
The families
| family | classes | explained |
|---|---|---|
| Identity and actors — who is acting, and the keys and ceremonies that prove it | 33 | 9 |
| Machines and seats — admitting a machine, seating work on it, retiring it | 49 | 5 |
| Dispatch and capacity — why work went to one place and not another, or nowhere | 21 | 4 |
| The record and gates — the workspace, its log, and the decisions written into it | 37 | 2 |
| The network path — what a run may reach, and why a connection was refused | 19 | 19 |
| The console — the browser surface, its certificate, and the acts it offers | 21 | 4 |
| Documents and contracts — signed instructions and schema versions | 11 | 3 |
| What is not yet explained — the 145 named-only classes in one list | — | — |
191 classes in, 191 classes out. 33 + 49 + 21 + 37 + 19 + 21 + 11 = 191, and no class appears in two families.
The defects your agents measured
Defects about the system itself are written down as files carrying the measurement that found them, checked against a fixed shape, and counted by class — and repair stays a human decision.
Every refusal class, A to Z
All 191 refusal classes the product declares, each with its family and whether this section explains it yet.