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 — 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.

See also

• Error handling
• OCC & atomicity
• Debugging
• @lunora/errors