ErrorsCopy page

A failure from the client is an OkmError. Import the class from okmodel.

import { OkmError } from "okmodel";

export function respond(error: unknown) {
  const err = OkmError.from(error); 
  return err.toHttp();
}

code is an OKM1xxx guard, or the kind name when that kind has no number. kind selects the category. summary is the same text as message.

Fields

fields() maps each column to a reason. The same object comes back on later calls. It has no row values.

values() returns row values only when the error was built with includeValues. Errors on connect is where that flag is set. log() returns the structured record: name, code, kind, category, summary, retryable, batch index, fix, fields, and table, columns, constraint, SQLSTATE, and issues when they are set. It leaves the row values out, and so does toHttp(). The logger on the client receives { code, summary }.

toHttp() returns { status, body }. The body is { code, reason, fields }. reason is the summary. A category missing from the status map keeps the default in the table below.

match runs the handler for this category. _ runs when that category is omitted.

import { OkmError } from "okmodel";

export function formOrHttp(error: OkmError) {
  return error.match({
    input: (item) => item.fields(), 
    conflict: (item) => item.fields(), 
    _: (item) => item.toHttp(), 
  });
}

OkmError.is narrows the kind, and the table when you pass one.

import { OkmError } from "okmodel";

export function emailTaken(error: unknown): boolean {
  return OkmError.is(error, "unique", "notes"); 
}

OkmError.from returns an OkmError unchanged. A DriverError whose kind is timeout, cancelled, or outcome_unknown keeps that kind. Any other thrown value becomes kind driver and code driver. from does not read constraint SQLSTATEs. The client does that before a query rejects.

A query exposes the same settlement as safe from okmodel.

import { db } from "./db.ts";

export async function addNote(title: string) {
  const result = await db.notes.insert({ title }).safe(); 
  if (!result.ok) return result.error.summary;
  return result.value;
}

{ ok: true, value } is success. { ok: false, error } is the mapped OkmError.

Kinds

ERROR_KINDS and ERROR_CATEGORIES are exported from okmodel. The constructor derives the category from the kind. A transient kind retries, except cancelled. outcome_unknown is internal, and it does not retry.

Pass http on connect, or pass statuses to toHttp(statuses), to replace one of these. A category you leave out keeps the status in the table. The connect page is Errors.

When the constructor is given no fix, the kind supplies one sentence.

A fix passed in replaces that sentence. A rejected name that is close to an accepted one appends a did-you-mean hint to the summary and sets fix.suggestion to that name.

Which code, which kind

Three codes pick a kind when the caller does not pass one.

A code that is itself a kind name uses that kind. A mapped database error does this for every kind except outcome_unknown. The client also raises invalid, not_found, not_unique, timeout, cancelled, unavailable, and forbidden with the kind as the code. Every other OKM1xxx, with no kind passed, is invalid.

Four codes pass a kind other than that default.

Driver failures

The adapter normalises the driver exception into DriverError. postgres.js and node-postgres put the SQLSTATE on code. Bun.sql puts ERR_POSTGRES_SERVER_ERROR on code and the SQLSTATE on errno. The copied fields are sqlstate, constraint (constraint_name or constraint), table (table_name or table), column (column_name or column), detail, and batchIndex.

cancelled() is the caller's signal. timedOut() is a statement, transaction, or batch deadline. outcomeUnknown() is a commit whose result never arrived. Those three stay DriverError until the client maps them. acquireTimeout() is already OkmError OKM1846. A closed pool is a DriverError with SQLSTATE 08006.

The client maps that error. An OkmError passes through. A driver kind of timeout, cancelled, or outcome_unknown wins over the SQLSTATE. 57014 without one of those kinds is timeout, because cancelled comes only from the signal.

Anything else is kind driver. With no SQLSTATE, a TLS failure or a dropped connection is unavailable.

The connection codes are ECONNRESET, ECONNREFUSED, EPIPE, ENOTFOUND, ETIMEDOUT, CONNECT_TIMEOUT, EHOSTUNREACH, ENETUNREACH, EAI_AGAIN, CONNECTION_CLOSED, CONNECTION_ENDED, CONNECTION_DESTROYED, and ERR_POSTGRES_CONNECTION_CLOSED. Classification reads the code, the errno, or the SQLSTATE. It does not read the message. A TLS cause starts with ERR_TLS_, ERR_POSTGRES_TLS_, or SELF_SIGNED_CERT_, or is exactly DEPTH_ZERO_SELF_SIGNED_CERT or UNABLE_TO_VERIFY_LEAF_SIGNATURE.

These SQLSTATEs keep their kind and add a reason.

fields() uses that reason. With a schema, the reason is the catalog object's name key for the columns the error names. With no schema, table_pkey becomes pkey, and a trailing _fkey, _check, or _key is removed. No constraint name leaves the kind as the reason.

Bun.sql and PGlite reject a positive timeout as OKM1120. The message is timeout. The kind is invalid. They cannot cancel a statement that is already running.

Doctor

okm doctor OKM1020 prints the registry entry: the code, the title, the summary, and the fix.

OKM1020: Unknown table
A table, dependency, or catalog object is missing or does not match its identity.
Use a name that is in the schema. The error lists the accepted names and a nearest-name hint when one is close.

An unknown code throws OkmError with code invalid. The message is Unknown code, then the argument, then a period. The fix says to pass a code from the registry, or to run okm doctor with no argument.

With no code, the command lists each table's triggers, one line per table, or no triggers. When the config sets roles, it also connects and checks that those roles exist, that a managed role can be created, and that the application role can reach each managed object. The command does not change the database.

The registry is not on the runtime entry. A process that never explains a code does not load it.

Registry

The registry has 110 codes, in numeric order. Ranges are schema OKM1000, queries and capabilities OKM1100, validation OKM1200, mapped database errors OKM1300, transactions OKM1400, migrations OKM1500, typed SQL OKM1600, tenancy and policies OKM1700, drivers and versions OKM1800, and CLI OKM1900. Mapped database errors use the kind as the code, so OKM1300 has no entry. OKM1900 has no entry. The tables below are every code the registry holds.

Schema

Queries and capabilities

Validation

Transactions

Migrations

OKM1538, OKM1539, OKM1540, OKM1543, OKM1544, OKM1545, and OKM1552 are warnings. A warning is printed and the command still succeeds. An error blocks plan, check, and apply.

Typed SQL

Tenancy and policies

Drivers and versions