> For the complete documentation index, see [llms.txt](https://fifo-docs.gitbook.io/colibri/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://fifo-docs.gitbook.io/colibri/colibri-core/error.md).

# Error Handling

Most Core, WebAuth, build-verification, identicon, and plugin failures use `ColibriError` or a subclass. [**RPC Streamer**](/colibri/colibri-rpc-streamer/rpc-streamer.md) **and Test Tooling have their own `Error` subclasses** ([`RPCStreamerError`](/colibri/colibri-rpc-streamer/recovery.md#error-shapes) and [`QuickstartError`](/colibri/colibri-test-tooling/configuration.md#error-handling)). RPC libraries and application callbacks can also throw other values; do not assume every caught error has a Colibri shape.

## The shared error shape

| Field        | Meaning                                                         |
| ------------ | --------------------------------------------------------------- |
| `domain`     | Broad area such as processes, pipelines, or tools               |
| `source`     | Owning module identifier, not necessarily an importable subpath |
| `code`       | Stable machine-readable condition                               |
| `message`    | Human-readable explanation; not a stable matching key           |
| `details`    | Optional additional context                                     |
| `diagnostic` | Optional root cause, suggestion, and reference links            |
| `meta`       | Domain-specific input, data, and/or original cause              |

`toJSON()` exposes the structured fields. Error metadata may contain transaction inputs or other sensitive application data; redact it before sending logs to a third party. Serialization alone is not a privacy guarantee.

## Narrow to a particular occurrence

```ts
import { BTX_ERRORS, ColibriError } from "@colibri/core";

function report(error: unknown): void {
  if (error instanceof BTX_ERRORS.COULD_NOT_LOAD_ACCOUNT_ERROR) {
    console.error("Source lookup failed", error.meta.data.input.source);
    console.error(error.meta.cause?.message);
  } else if (ColibriError.is(error)) {
    console.error(error.source, error.code, error.message);
    console.error(error.diagnostic?.suggestion);
  } else {
    console.error("Non-Colibri failure", error);
  }
}
```

Pass a caught value to this handler. A code comparison is useful for application routing; a concrete exported class/registry also gives typed metadata. Different contexts may use different constructor names for the same conceptual condition. Use the actual exported registry instead of inventing an import from a source path.

## Dedicated classes across packages

Every library-owned stable code has its own concrete class. This also applies to React (`ReactErrors`), WebAuth (`WebAuthErrors`), Identicon (`IdenticonErrors`), contract bindings (`BindingErrors`), [RPC Streamer](/colibri/colibri-rpc-streamer/rpc-streamer.md) (`RPCStreamerErrors`), and Soroban values (`SorobanErrors`). The registry maps codes to exported constructors; family-level catches continue to work. Core's unclassified fallback is `UnexpectedError` ([`GEN_000`](/colibri/reference/errors/core.md)). [RPC Streamer](/colibri/colibri-rpc-streamer/rpc-streamer.md) retains its established `details` object and native `cause` shape.

Legacy public family constructors are retained for source compatibility and extension, but library implementation sites must use dedicated subclasses. `ColibriError` remains the extensible base for consumer-owned codes. Existing Colibri errors and caller-owned errors retain identity at passthrough boundaries. Architecture tests inventory all workspace packages and reject missing, shared or duplicated concrete error classes, as well as generic coded-error construction in library implementations.

## Recovery belongs to the caller

* Invalid configuration: correct input before retrying.
* Source/RPC lookup failure: inspect the underlying cause and the chosen network.
* Simulation/contract failure: inspect diagnostics and the contract's error enum.
* Submission timeout: query the existing transaction hash before constructing another transaction. A missing confirmation is not proof of non-execution.
* Build mismatch: a completed verification result, not an exception; compare its evidence before changing the recipe.

`ColibriError.fromUnknown()` preserves existing Colibri errors and wraps other values. Its default fallback code is [`GEN_000`](/colibri/reference/errors/core.md); applications may supply their own source/code. Do not collapse a known occurrence into that fallback.

## Complete references

[All error contexts](/colibri/reference/errors.md) lists every declared code in the published package source. The references include declarations that are not currently emitted and internal contexts that can surface through public calls. They do not imply that every context has a root-exported constructor.

See [streamer recovery](/colibri/colibri-rpc-streamer/recovery.md), [WebAuth JWT/error handling](/colibri/colibri-webauth/jwt.md), and [Quickstart configuration](/colibri/colibri-test-tooling/configuration.md) for their package-specific boundaries.