Typed Errors

Turbine throws typed errors you can catch with instanceof or by code. Every error Turbine RAISES extends TurbineError and carries a stable readonly code field for programmatic handling. The one exception is a driver error whose SQLSTATE Turbine does not map: it reaches you as the driver's own error, with the SQLSTATE on .code and .sqlstate, in both message modes. See unmapped SQLSTATEs below. Messages start with the same code tag (e.g. [TURBINE_E008] …) so logs are greppable, but do not parse the message; branch on err.code / instanceof. Postgres driver errors (23505, 23503, 40P01, etc.) are translated into typed classes via wrapPgError().

err.code is the check that survives any module graph. A process that loads the package twice, once as ESM and once as CommonJS (a "type": "commonjs" project whose generated client is required while an .mts entry imports the package, a CJS library that wraps Turbine, a Jest setup), holds two copies of every class, and a plain prototype-chain instanceof against the other copy is false. Since 0.78 instanceof works across copies too: every error carries a cross-copy brand and each class implements Symbol.hasInstance over that brand and the error's code, so err instanceof UniqueConstraintError is true whichever copy threw it. The code comparison needs no import at all, which makes it the right check in a shared handler or a library.

Every error also carries readonly docsUrl (e.g. https://turbineorm.dev/errors#e008, an anchor into the table below), and its message ends with the same link, so structured sinks get the URL as a field without parsing anything. A unit test asserts every code has its row and anchor here, so a new code cannot ship undocumented.

Error code table#

Catching typed errors#

Import the classes from the package root and narrow with instanceof.

import {
  NotFoundError,
  ValidationError,
  TimeoutError,
  UniqueConstraintError,
} from 'turbine-orm';
 
try {
  const user = await db.users.findUniqueOrThrow({ where: { id: 999 } });
} catch (err) {
  if (err instanceof NotFoundError) {
    // err.code === 'TURBINE_E001'
    // err.table, err.where, and err.operation are all populated
    return { status: 404 };
  }
  if (err instanceof ValidationError) {
    // err.code === 'TURBINE_E003'
    return { status: 400, message: err.message };
  }
  if (err instanceof TimeoutError) {
    // err.code === 'TURBINE_E002'
    // err.timeoutMs is the configured limit
    return { status: 504 };
  }
  throw err;
}

Unknown field names#

Every name you supply is resolved against the schema, and one that does not resolve throws TURBINE_E003 naming the table and, where it can, the column you probably meant. That holds for where, orderBy, distinct, groupBy keys, aggregate targets, create/update data, and select / omit, at every depth including inside a relation. There is no partial mode: a name is never dropped and the query never runs without it.

Naming a relation in select or omit gets its own message, because it is usually a habit carried over from Prisma rather than a typo:

[TURBINE_E003] "comments" is a relation on table "post", not a column, so it
cannot be named in `select`. Load it with `with: { comments: true }`, which is
a sibling of `select`, not a member of it.

Relations live in with, which sits beside select rather than inside it. To narrow a relation's own columns, put a select inside that relation's options: with: { comments: { select: { body: true } } }.

wrapPgError translation#

Every query execution runs its pg error through wrapPgError(). The original driver error is preserved as .cause on the wrapped error.

For these codes the offending value sits in the driver's own message text, so the wrapped ValidationError is built the other way round from the constraint classes: its message names the column (when the driver reports one), a value-free account of the problem (the value could not be parsed as the column type, the number is out of range for the column type, ...) and the SQLSTATE. Under errorMessages: 'verbose' the account is the driver's text and .detail carries it; under the default 'safe' mode the driver's text is kept out of the message, out of .detail, and out of the .cause error's message. Any other SQLSTATE stays outside the TurbineError hierarchy (no TURBINE_ code, and .code is the SQLSTATE): under 'safe' it is returned as a clone of the driver error whose message reads Database error <SQLSTATE>, with .detail redacted and the original error on .cause; under 'verbose' the raw driver error is returned as-is, because its message grammar is unknown to Turbine and only the verbose mode has asked to see it.

import { UniqueConstraintError } from 'turbine-orm';
 
try {
  await db.users.create({ data: { email: 'taken@example.com', ... } });
} catch (err) {
  if (err instanceof UniqueConstraintError) {
    // err.constraint, e.g. 'users_email_key'
    // err.columns  , e.g. ['email']
    // err.table    , e.g. 'users'
    // err.cause    , the original pg error
    return { status: 409, message: 'Email already in use' };
  }
  throw err;
}

Retryable errors#

DeadlockError and SerializationFailureError expose a readonly isRetryable = true as const field, a type-level signal your retry loop can narrow on.

You do not have to write that loop. Turbine exports withRetry, and TurbineClient exposes the same thing as db.$retry:

import { withRetry } from 'turbine-orm';
 
await withRetry(() =>
  db.$transaction(
    async (tx) => {
      const row = await tx.counters.findUniqueOrThrow({ where: { id: 1 } });
      await tx.counters.update({
        where: { id: 1 },
        data: { value: row.value + 1 },
      });
    },
    { isolationLevel: 'Serializable' },
  ),
);

withRetry(fn, options?) retries only when the thrown error carries isRetryable === true, and rethrows anything else immediately. Options: maxAttempts (default 3), baseDelay in ms (default 50), maxDelay (default 5000), and an onRetry(error, attempt) hook. Backoff is exponential with jitter, capped at maxDelay. db.$retry(fn, options) is the same function bound to the client.

Pipeline errors#

PipelineError is only thrown when a pipeline runs in non-transactional mode ({ transactional: false }) and one or more queries fail. It carries a per-query result array so you can inspect exactly which succeeded and which failed.

import { PipelineError } from 'turbine-orm';
 
try {
  await db.pipeline(queries, { transactional: false });
} catch (err) {
  if (err instanceof PipelineError) {
    // err.results: ({status:'ok', value} | {status:'error', error})[]
    // err.failedIndex: zero-based index of the first failed query
    // err.failedTag: DeferredQuery.tag of the first failure
    for (const [i, slot] of err.results.entries()) {
      if (slot.status === 'error') {
        console.error(`Query ${i} failed:`, slot.error);
      }
    }
  }
}

Transactional pipelines (the default) either fully succeed or roll back, a failure surfaces as whichever typed error the failing query raised.

Unsupported features on other engines#

UnsupportedFeatureError (TURBINE_E017) is thrown when you invoke a Postgres-only feature on one of Turbine's other database engines, SQLite, MySQL, or SQL Server. It is not a wrapPgError() translation; Turbine raises it directly (from a capability flag on the active dialect) instead of generating broken SQL. The Postgres-only features are pgvector distance ops, LISTEN/NOTIFY realtime ($listen / $notify), and RLS sessionContext ($withSession).

import { UnsupportedFeatureError } from 'turbine-orm';
import { turbineMysql } from 'turbine-orm/mysql';
 
const db = await turbineMysql(process.env.MYSQL_URL!, SCHEMA);
 
try {
  await db.$listen('orders', (payload) => console.log(payload));
} catch (err) {
  if (err instanceof UnsupportedFeatureError) {
    // err.code    === 'TURBINE_E017'
    // err.feature === 'LISTEN/NOTIFY'
    // err.dialect === 'mysql'
  }
}

TURBINE_E017 is not a "wrong engine" error in general, though. It is the code for this build cannot do that, and Postgres raises it too:

• relationLoadStrategy: 'batched' on a composite-key relation, including a composite-key many-to-many junction. The batched loader keys on one column, so it refuses instead of loading a wrong set. Use the default join plan for those relations.
• relationLoadStrategy: 'batched' where the correlation key is missing from every parent row. The batched loader stitches in JS, so it needs that column in the rows it was handed; without it the relation would come back silently empty, so it refuses instead, naming the relation and the key. This should not be reachable; if you hit it, report it, and use relationLoadStrategy: 'join' on that query meanwhile.
• On turbine-orm/prisma-compat, a Prisma shape with no Turbine equivalent: a negative take, skip on a nested include, the inclusive-cursor shapes that cannot be translated exactly, limit on updateMany / deleteMany, and $extends with a query or result component (or any component the adapter does not implement, refused at $extends time with the alternative named).

Catch on err.code === 'TURBINE_E017' and read err.feature, which names what was refused. See Database Engines for the full capability matrix.

The same error carries PowDB's version-gated capabilities, where the feature exists but the connected engine is too old for it. Those messages name the feature once and then give the floor and what the connection reported:

[TURBINE_E017] JSON path filters is unsupported on "PowDB". Requires PowDB >= 0.12;
this connection reports 0.11.0. Upgrade powdb-server / @zvndev/powdb-embedded
(or pass `assumeEngineVersion` if the version cannot be detected).

Some gates append one more sentence naming a workaround. err.feature is the label from the first sentence, err.dialect is 'PowDB'.

Read-only refusals#

ReadOnlyError (TURBINE_E018) is the routing signal for writes that hit a read-only database. Its reason field tells you which kind:

• 'snapshot', the database itself is read-only: a PowDB --readonly snapshot server, an embedded { readonly: true } open, or Turbine's own client-level readonly: true fail-fast flag. Nothing can write here; route the write to your primary.
• 'rbac', the database is writable but this connection's role may not write (permission denied: role …). Re-authenticating with a writer role may suffice.
• 'transaction' (since 0.90), the transaction is read-only: one opened with BEGIN READ ONLY or SET TRANSACTION READ ONLY, or any transaction on a hot-standby read replica. PostgreSQL SQLSTATE 25006 and MySQL error 1792 map here; before 0.90 they surfaced as a generic database error. Run the write in a read-write transaction on the primary. A write inside $transaction(fn, { readOnly: true }) lands here too. An exhaustive switch over reason needs the new case.

import { ReadOnlyError } from 'turbine-orm';
 
try {
  await replica.orders.create({ data });
} catch (err) {
  if (err instanceof ReadOnlyError && err.reason === 'snapshot') {
    await primary.orders.create({ data }); // route to the writer
  }
}

See Read Replicas for the snapshot-serving pattern this supports.

Safe error messages#

By default, NotFoundError messages include only the keys of the where clause; values are redacted so PII does not leak into logs (Sentry, Datadog).

[TURBINE_E001] findUniqueOrThrow on "users" found no record matching where: { id, email }

The full where object is always available as err.where for programmatic access, only the human-readable message is redacted. Since 0.90 where is not enumerable in safe mode, so JSON.stringify(err) and error serializers that walk own properties do not carry it into logs; read err.where directly. Opt into verbose messages (useful in local development) by setting errorMessages: 'verbose' in your TurbineConfig, or by calling setErrorMessageMode('verbose') at startup.

const db = turbine({
  connectionString: process.env.DATABASE_URL,
  errorMessages: process.env.NODE_ENV === 'development' ? 'verbose' : 'safe',
});

What safe mode redacts#

Safe mode redacts the four PostgreSQL error fields that can carry a row value: detail, hint, where (the CONTEXT line) and internalQuery. Each is replaced on both the returned error and on .cause, so nothing a logger walks holds the value. hint is the one most often missed, because a RAISE ... USING HINT interpolates whatever the function author put there, and internalQuery carries the text an EXECUTE format(...) built, bound values included.

Unmapped SQLSTATEs#

A driver error whose SQLSTATE has no typed class reaches you as the driver's own error, not a TurbineError. That is the same in both message modes, deliberately: verbose has always returned the raw error, and minting a typed error only under safe would make one database failure land in different catch branches depending on a logging setting.

It carries the SQLSTATE on .code, and on .sqlstate under the name the typed errors use:

try {
  await db.orders.findMany();
} catch (err) {
  if (err instanceof TurbineError) handleTyped(err);
  else if ((err as { sqlstate?: string }).sqlstate === '42P01') runMigrations();
}

Under safe the message is kept when the SQLSTATE class's grammar cannot hold a row value, and withheld when it can:

A withheld message says so and names the setting that shows it:

Database error P0001 (driver text withheld by errorMessages: 'safe'; set errorMessages: 'verbose' to see it)

See also#

• API Reference, transactions, pipelines, and the queries that raise these errors.
• Schema & Migrations, MigrationError fires here.
• Database Engines, where UnsupportedFeatureError comes from and the per-engine capability matrix.