The error model

Every error Adonia raises extends AdoniaException and carries a stable E_ADONIA_* code. Codes are public contract: match on error.code, never on the message. They do not change within a major version.

The codes

The upload family shares one base — UnsupportedUploadTypeException, UploadTooLargeException and InvalidImageDimensionsException all extend UploadRejectedException — so a client that only wants “the upload was refused” catches the base and one that wants a specific message switches on the code. All four are 422 rather than 400: the request is well-formed HTTP addressing a real field, and it is the CONTENT that fails the field’s rules.

AdoniaException itself carries E_ADONIA at 500. It is the base, not a code any thrower uses, and it is what an error reaching the handler without a subclass code reports.

Two renderings, chosen by Accept

AdoniaException defines handle(error, ctx), which v7’s ExceptionHandler prefers over its own rendering. The branch therefore lives on the error, and a host app that replaces its exception handler keeps it.

• JSON endpoints (request.accepts(['html','json']) === 'json', or no Inertia on the context) → { code, message } at the exception’s status. message is error.detail: the message without the [E_ADONIA_*] prefix that error.message carries, since the code already rides beside it.
• Browsers and Inertia XHR → the adonia/error page (below).

Both responses are Cache-Control: no-store. They depend on who asked (abilities, tenant) and on state expected to change, so a shared cache holding one would serve a stale 403 or a resolved 404 to somebody else.

The adonia/error page

One page serves 403, 404, 500 and every other status. Props are AdoniaErrorPageProps, built by errorPageProps in packages/core/src/errors.ts:

import type { AdoniaErrorPageProps } from '@adonia/core'

const props: AdoniaErrorPageProps = {
  status: 404,                              // number
  code: 'E_ADONIA_UNKNOWN_RESOURCE',        // string | null — null for a foreign error
  message: null,                            // string | null — error.detail in development, ALWAYS null in production
  title: 'Not found',                       // string — keyed by status, not by code
  description: 'That page does not exist.', // string — generic, always safe to show
  backUrl: '/admin',                        // string | null — the panel mount path
}

title/description are keyed by status, not by code: the reader is a panel user, for whom E_ADONIA_UNKNOWN_FIELD and E_ADONIA_UNKNOWN_RESOURCE are both “that does not exist”. A status with no copy of its own falls back by class (4xx vs 5xx), so a new code renders sensibly without a table edit.

message is the one leak-prone member, so the server — not the page — decides it. In production the page receives null and has no other source for the text; a leak is impossible by construction rather than by discipline. code is shown in production: it is documented contract, it is what a support ticket should quote, and it reveals nothing the docs do not.

Overriding it

The React half is ErrorPage from @adonia/ui/pages, scaffolded into the host app as inertia/pages/adonia/error.tsx. Two levels of override:

// inertia/adonia.ts — replace the body, keep the panel chrome.
import { adonia } from '@adonia/ui'

export default adonia({
  registry: (r) => r.page('error', MyErrorBody),   // props: ErrorPageProps
})

# Replace the whole page, chrome included.
node ace adonia:eject error

The registry override is the usual one: a branded 404 belongs inside the sidebar the user was already looking at, not on a bare white page.

Foreign errors inside a panel route

A TypeError in a resource query(), a Lucid E_ROW_NOT_FOUND, anything the app throws from a transformer — none of them are AdoniaExceptions, and without help they escape to the app’s global handler, dropping the visitor out of the panel on a route the panel owns.

PanelErrorMiddleware is a boundary applied to each panel route group (after the panel slot and the §9.1 share hook, before the access gate and the app’s own panel.middleware([...])). It renders the same chromed page. It is scoped to panel groups on purpose: Adonia has no business deciding how the host app renders errors on its own routes.

It re-throws — leaving the error to the app’s handler, exactly as before — when:

• the error is an AdoniaException (it renders itself);
• the error defines its own handle (v7’s self-handling protocol: hijacking it would turn a validation redirect-back or an auth challenge into a 500 page);
• the client wants JSON (there is no Adonia code to put in the body for a foreign error, so the host handler’s shape is the honest answer);
• there is no Inertia or no panel on the context (no chrome to render into).

An error carrying its own 4xx/5xx status keeps it; anything else becomes 500. A 5xx is written to ctx.logger before the page is sent, because the visitor only ever sees generic copy and operators still need the stack.

Tests

• packages/core/tests/errors.spec.ts — every code’s class/status/detail, a rendered-page test and a JSON-endpoint test per code, the production no-leak assertion per code, the copy fallbacks, and the boundary’s re-throw/render matrix.
• packages/ui/tests/error_page.test.tsx — chrome, copy, the dev-only detail, and the r.page('error', …) override.