Errors

Last updated 29 October 2026

The error classes the package throws, each kind, when it happens and what to do.

Every class extends UrsulaError and is exported by @tonbo/sqlite-ursula and /tonbo; TonboError by /tonbo alone. Any other error, such as a constraint violation or a syntax error, is node:sqlite’s, unchanged. Symptoms and their fixes are on Troubleshooting.

UrsulaError

class UrsulaError extends Error {
  readonly kind: UrsulaErrorKind;
  readonly action: "retry" | "reopen" | "stop" | "fix";
  readonly cause?: unknown;
  readonly code?: string;    // node:sqlite's, when cause is its error
  readonly errcode?: number;
  readonly errstr?: string;
}

kind names what failed and action what to do: branch on action. cause is the error the failure surfaced as, usually SQLite’s, whose code, errcode and errstr are copied, so code that reads them keeps working. Network failures never throw from statements or synced(): they wait.

import { UrsulaError } from "@tonbo/sqlite-ursula/tonbo";

try {
  db.prepare("INSERT INTO notes(body) VALUES (?)").run(body);
} catch (error) {
  if (!(error instanceof UrsulaError)) throw error; // a constraint, a syntax error
  if (error.action === "retry") await db.synced(); // then run the transaction again
  else throw error; // reopen, stop or fix
}

Actions

UrsulaErrorAction. The extension names each failure’s kind, action and class, the error to throw, through ursula_classify since 0.11.2, so a kind this page does not list, from a newer extension, carries the extension’s action; 0.11.1 said fix for such a kind. Messages are the extension’s too.

UrsulaErrorKind is every kind on this page: the union of WriteRefusedKind, ResetKind, UnavailableKind, SetupKind and TonboKind.

UrsulaWriteRefusedError

A write or COMMIT refused with nothing committed: SQLite rolled the whole transaction back, and the database stays usable. Its errcode is 7178, SQLITE_IOERR_AUTH, and status().refused keeps the last one.

UrsulaResetError

The database was reset. Every statement of it throws this, reads included (errcode 266 for a read, 778 for a write), synced() rejects with it, and the reset listeners get it. See After a reset.

UrsulaUnavailableError

open() found no trusted state in time: its signal fired while the stream, or for an open by name the Tonbo API, did not answer as it must. kind is the last condition it met, or cancelled when it met none. A token provider that handed out no token in time rejects the open with unavailable, its last error as the cause. From importSqlite() every kind says fix, since the stream may hold the import’s claim.

UnavailableKind also names wrong_cluster, but the package throws it as an UrsulaSetupError.

UrsulaSetupError

open(), resolveDatabase() or importSqlite() cannot succeed as asked, or a database that retired was asked for synced() or status(). Its message says what to change.

TonboError

From /tonbo, since 0.11.1. A key, a login or a database to fix: the action is always fix. fix holds what to do, the variable to set or the command to run, and the message ends with it. requestId is the Tonbo API’s id of the answer that failed, when one did; quote it to support.

class TonboError extends UrsulaError {
  readonly kind: TonboKind;
  readonly fix: string;
  readonly requestId: string | undefined;
}