Errors & warnings reference

Every error Lunora throws carries a machine-readable code. The code keys into a central catalog that supplies the transport status, a human title, and (for the codes where it helps) an actionable hint. The same catalog drives the CLI renderer, the Vite error overlay, the Studio, and the client SDK, so an error reads the same wherever you meet it.

import { isLunoraError } from "@lunora/errors";

if (isLunoraError(error)) {
    error.code; //   "CONFLICT"
    error.status; // 409
    error.hint; //   actionable Markdown, when the catalog has one
}

isLunoraError matches structurally, on a string code plus a numeric status, so it also recognises errors rebuilt from the wire, where instanceof cannot be trusted.

Request errors

Client helpers exist for the ones you branch on most: isUnauthorizedError, isForbiddenError, isRateLimitedError (plus getRetryAfterMs), and isConflictError, all from @lunora/client.

Data errors

CONFLICT

Another write changed the row while your mutation was running. Re-read the row and retry with the fresh value.

Because Lunora serializes a DO's mutations, a persistent conflict usually means the handler conflicts with itself: a trigger or cascade touching the same row. Split that work rather than adding a retry loop. See OCC & atomicity.

A unique-index breach on the write path also surfaces as CONFLICT, with the message unique constraint violation on <table>. That one is different: either upsert (or patch the existing row) instead of inserting, or pick a value that is not taken.

NOT_UNIQUE

.unique() expects the query to identify at most one row. If several matches are legitimate, use .first() or .collect() instead; otherwise tighten the query so it can only match one row.

Authorization and privacy errors

RLS_REQUIRED

The table has no .public() marker and no RLS policy resolved for this caller, so the read fails closed. Add a read policy with .rls(...), or mark the table .public() if it is genuinely world-readable.

Dispatch errors

Infrastructure errors

The three *_ERROR codes carry Cloudflare's own error text (trusted infrastructure rather than user input), so the upstream message is echoed rather than redacted, and the actual upstream HTTP status is passed through.

Auth and email errors

Tune the domain policy with blockDisposable / allowDomains / denyDomains on emailGate(...) in @lunora/auth/email-guard. MX verification is opt-in (mx: true) and needs DNS, so leave it off on an edge path where DNS is not available.

Internal errors

These are redacted on the wire: their messages may carry SQL fragments, file paths, or internal identifiers, so the transport emits a generic message and logs the real one server-side.

Throwing a LunoraError with any non-internal code is your vouch that its message is safe to show a client. invariant(...) and unreachable(...) throw INTERNAL, so "should never happen" assertions are redacted automatically.

Build-time errors

These never cross the RPC wire.

Codegen errors are thrown as plain messages rather than codes, so Lunora matches them by message text and attaches a solution. The ones with dedicated guidance:

Throwing your own

LunoraError takes a code and a message, and fills in status, title, and hint from the catalog:

import { LunoraError } from "@lunora/errors";

throw new LunoraError("NOT_FOUND", `no message with id ${id}`);

Explicit options override the catalog defaults. For errors you expect the client to branch on, see Error handling.