RFC: Qwik v2 error handling — PublicError, fail(), and ErrorBoundary

[maiieul]

RFC status: design proposal — implementation not started. This proposes the complete
error-handling model for Qwik v2 across loaders, async computeds, server$, middleware, and
actions. It removes ServerError in favor of two symmetric mechanisms — PublicError (inline,
user-facing) and fail() (document abort) — on top of the closest-parent <ErrorBoundary>.
The test specs at the end are the acceptance criteria. Feedback welcome on every section.

Scope: loaders, async computeds, server$, middleware/endpoints, and actions.
Terminology: async computeds = useComputed$(async () => …) — the async API is merged back
into useComputed$ (the old useAsync$ name is gone). Loaders are async computeds under the
hood. Internal impl names (AsyncSignalImpl, async-signal-impl.ts) keep the "async-signal"
naming. .loading is renamed to .pending everywhere.

Evidence base: verified competitive research (July 2026) on SvelteKit 2 / React Router 7-8 /
TanStack Start / Nuxt 3-4 / SolidStart, plus cross-ecosystem precedents (GraphQL-over-HTTP,
tRPC, DataLoader, ESLint configs, Google soft-404 guidance, RFC 9111 caching, Next.js doctrine).
Every claim was checked against current official docs; §8 condenses it. Ask in the thread for
any specific source.

1. The model

Every error in a Qwik app is exactly one of three kinds:

Kind	Meaning	API	Where it lands	Response status
Inline	Expected, user-facing failure data ("out of stock", "profile is private")	throw new PublicError(data) — core class, free import, usable anywhere	signal.error, read via a guard; page keeps rendering. Unguarded .value reads re-throw it into the closest boundary — never a silent failure	untouched
Abort	This document cannot/should not render	throw fail(status, data) — event-arg method, loaders + middleware only	route's error.tsx chain (or generic error page)	the given status
Unexpected	A bug or infra failure nobody planned for	any other throw	closest <ErrorBoundary>; redacted in prod	500 when nothing catches it

Four principles generate everything else:

1. Aborts are never read by user code; inline errors always are. You throw an abort and the
   framework handles it server-side (never instanceof, never .data in app code). You read an
   inline error back at loader.error. So the abort is an ergonomic FUNCTION (a verb — an action
   you take) and the inline is a CLASS (a noun — a value you hold and read). The syntactic distance
   (fail(...) call vs new PublicError(...)) is itself the disambiguator.
2. Return = data, throw = control flow. One rule, everywhere, both directions: control-flow
   objects must be thrown (a resolved PublicError is a dev-time error, not a secret throw), and
   returned values are always data. The single, deliberate exception is the deprecated v1 compat
   channel return fail() → .value.failed.
3. Status belongs to the document. Only the abort channel carries an HTTP status. Inline errors
   are data — no status field, no status side effects (see §6 for the research grounding).
4. Safe-by-contract. Constructing a PublicError is consent to serialize and display its data.
   Everything else fails closed: redacted, never serialized, never rendered.

Where any throw ends up:

flowchart TD
    T["throw / rejection inside a loader or async computed"] --> P{"instanceof PublicError?"}
    P -- "yes" --> INL["inline: stored on signal.error<br/>page keeps rendering, status untouched"]
    INL --> G{"component guards .error?"}
    G -- "yes — early return" --> UI["friendly error UI renders"]
    G -- "no — .value is read" --> RT["LOUD: .value re-throws the PublicError<br/>(an unguarded inline error never fails silently)"]
    RT --> EB
    P -- "no" --> F{"branded fail() carrier?"}
    F -- "yes, pre-stream" --> AB["abort: response status set,<br/>error.tsx chain renders"]
    F -- "yes, but stream started<br/>(blockSSR:false)" --> U
    F -- "no" --> U["unexpected: internal rejection<br/>(never on .error — reads it as undefined —<br/>never serialized)"]
    U --> R[".value read re-throws it"]
    R --> EB["closest ErrorBoundary renders fallback"]
    EB -. "no boundary" .-> ESC["render rejects → generic error page"]

Loading

2. The inline channel: PublicError

// @qwik.dev/core — public
export class PublicError<T = unknown> extends Error {
  constructor(public data: T) {
    super(typeof data === 'string' ? data : 'Public error');
  }
}

Design decisions, each with its rationale:

• A class, not bare Error. Unexpected errors (TypeError, fetch/db failures) are also
  instanceof Error, so bare-Error classification would make every accident "public" — internal
  messages would serialize into HTML and render through guards. Public errors are deliberate
  (the developer marks them); unexpected ones are accidents (nobody marks them) — the marker must
  live on the deliberate side and be checkable in $setError$, the .error getter, and the
  serializer, failing closed. Every surveyed ecosystem draws the expected/unexpected line at
  "did app code use the blessed constructor" (SvelteKit error() bypassing handleError, h3's
  unhandled flag, NestJS HttpException).
• Exported as a real class. SvelteKit deliberately hides its error classes and has lived with
  broken instanceof + guard-function workarounds ever since (#10361, #12611); a public class with
  first-class serdes support avoids that whole issue class.
• No status field — not even optional. No surveyed framework puts HTTP status on its
  inline/readable channel; tRPC/Apollo keep the semantic field (code) on the error and derive
  transport status. A field that is inert in loaders but honored in server$ would recreate
  Nuxt's documented dual-personality confusion (createError fatal on server, inert on client),
  and status is precisely the field that made the removed ServerError abort-shaped. If userland
  branching pressure ever appears, the right extension is a tRPC-style code field — never a
  status field. A code field is not part of this design.
• Throw-only; a resolved PublicError is a bug. No framework supports Error-instance
  return/throw parity on purpose (React Router refused it with a typing rationale; SvelteKit
  dev-enforces verb correctness; graphql-js's instanceof-on-resolve behavior is a documented
  gotcha that makes Error instances unrepresentable as data). When a loader/computed resolves
  with a PublicError instance, the framework raises a qError ("throw it instead") which flows
  down the unexpected channel — loud in dev and prod, no silent magic. A returned plain Error
  stays an ordinary value. Optional type-level hardening: constrain compute/loader return types so
  PublicError in the resolved type is a compile error.
• No form/field validation payloads. Soft validation is a value-channel concern (§5.4):
  thrown values cannot contribute to derived types, which is exactly why SvelteKit enforces
  return fail() for forms, and Next.js documents "model expected errors as return values".
  PublicError stays single-purpose: loud, gating, read at .error.
• Identity hardening. Own serdes TypeId so instanceof survives the wire (resumed .error
  state, loader.json envelope). Classifiers additionally accept a well-known Symbol brand on the
  class, so a duplicated @qwik.dev/core copy cannot silently break classification (the dual-copy
  instanceof failure is a documented TanStack Form hazard).
• Serdes traps: append the TypeId within the "All types below will be inflate()d" region
  (deser-proxy gates typeId >= TypeIds.Error); serialize branch BEFORE generic
  instanceof Error; keep dump-state typeIdToName in sync. Optional dev-mode eager
  serializability check on data in $setError$.

3. The abort channel: fail(status, data)

• An event-arg method for document-request contexts — loaders (({ fail }) => …) and
  middleware/endpoints (onRequest(({ fail }) => …)) — promoted from RequestEventAction to
  RequestEventCommon (a non-breaking addition). NOT a free import, NOT on components/client.
  This makes abort structurally server-only: a client-capable async computed has no fail() in
  scope, so it cannot abort. server$ and actions share the RequestEvent type but are
  imperative calls, not document renders — their error path is PublicError, and fail() is
  omitted from their this types.
• fail() sets the response status at call time (v1 behavior) and returns the failure
  carrier. THROWING the carrier is the abort; RETURNING it is the deprecated v1 inline channel
  (.value.failed). Same function — the verb routes it unambiguously.
• The carrier is an Error subclass ("FailReturn"), not a plain object, carrying own
  enumerable failed: true plus the spread data keys:
  • throw fail(...) stays lint-clean — throw {failed: true} fails
    @typescript-eslint/only-throw-error (in recommended-type-checked), airbnb, and standard,
    i.e. most typed apps in 2026 — and carries a stack for debugging.
  • return fail(...) compat holds: .value.failed === true and data keys read the same, and the
    Error serializer (message + own enumerable props) preserves the shape across the wire.
  • Compat constraint: v1's carrier was a plain object; .value.failed consumers, JSON
    expectations, and the serdes round-trip must keep reading identically (pinned by C5/D20).
• Recognition is a module-private Symbol brand, not failed === true. A rethrown API response
  body that happens to contain failed: true must NOT abort the request with a stale status.
  Aborts never serialize (the request ends server-side), so a Symbol is safe, and it is immune to
  package-duplication instanceof hazards. One predicate at every document catch site
  (loaders-middleware classifier, user-response catch, serverErrorMiddleware).
• No public abort class. You never read an abort, so there is nothing to instanceof in app
  code. (A named class was considered and dropped; AbortError would also collide with the DOM
  cancellation error that async signals swallow.)
• error(status, data) is kept as a deprecated shim producing the same branded carrier
  (deprecation message: "throw fail(status, data)"). Because ServerError leaves the control-flow
  set, return error() no longer aborts — it is an inert value (v1 no-op), undocumented.
• ServerError is REMOVED (breaking; it was v2-beta-only). Data-shape
  reconciliation: ServerError was {status, data} (any data); the carrier spread is
  object-only — string messages become { message: '…' }; internal
  throw new ServerError(status, 'string') sites (rewrite 400, malformed-URL 404) migrate to
  object data; mind fail()'s check() (it throws after headers are sent — the malformed-URL 404
  completion stays a bare post-headers object, not an ev.fail() call).
• throwIfControlFlowSignal keeps only AbortMessage/RedirectMessage/RewriteMessage. The carrier
  is never in it — a returned fail() stays .value.failed data.

v3 end state: throw fail(status, data) is the only abort; throw new PublicError(data) is the
only inline channel; error(), return fail()/.value.failed are removed.

4. Read semantics on async signals

All three getters compute-if-needed; on the server each throws the pending compute promise so SSR
always renders settled results (component bodies retry via the existing promise-retry machinery).

Read	No error	Inline error (PublicError)	Unexpected error
.value	the value	throws it → closest boundary	throws it → closest boundary
.error	undefined	returns the PublicError	undefined (falls through to .value → boundary)
.pending	in-flight status; false after settle; never throws errors	″	″

• Loaders/async computeds are LOUD. The guard is a plain early return:

  const order = useOrderLoader();
  if (order.error) {
    return <p>{order.error.message}</p>; // friendly branch
  }
  return <p>{order.value.items.length} items</p>; // throws into the boundary if un-guarded

  Forgetting the guard on code that can produce a PublicError is a loud throw into the nearest
  boundary — the desired failure mode. The loud throw is conditional on an error existing at
  runtime, not on the code containing a throw: a plain data loader just reads .value, no forced
  guard. (.error stays typed PublicError | undefined — throws aren't statically detectable.)

• $setError$ classification: DOM AbortError → ignored (cancellation); instanceof PublicError
  (or brand) → $untrackedError$ (serializes); anything else → internal rejection slot (never
  serializes — the signal serializes as invalid/NEEDS_COMPUTATION so the client recomputes).

• Timeout errors (the timeout option) are infrastructure → unexpected channel.

• A thrown fail() carrier inside a client-capable async computed is not a PublicError →
  unexpected → boundary (+ dev warn). Correct: client computes cannot abort an HTTP response.

• .value setter clears both error channels; a successful recompute clears .error.

5. Surface by surface

One error model across every consumer:

	loaders / async computeds	server$ (imperative RPC)	actions
run trigger	route/deps (auto) or read	await fn(args)	.submit(args)
in-flight	.pending	— (you await)	.pending
success	.value	the await return value	.value
thrown PublicError (loud)	.error; unguarded .value re-throws → boundary	await rejects with it; unhandled → boundary	.error; same gating as loaders
soft form-level error	—	—	.formErrors (string[])
soft field error	—	—	.fieldErrors (validator or invalid())
fatal → error page	throw fail(status, d)	— (no page to abort)	— (no page to abort)
unexpected	read throws → boundary	await rejects generic; unhandled → boundary	.submit() rejects; unhandled → boundary

Two rules generate the table: throw = loud/gating (PublicError → .error; fail() →
error.tsx; unexpected → boundary) and soft = validation/returned data (.formErrors /
.fieldErrors / .value). .error behaves identically in every column; fail() exists only
where there is a document to abort.

5.1 Loaders

What a loader author writes and what happens:

Developer writes	Channel	Behavior
throw new PublicError(d)	inline	signal.error, page renders, status untouched
return new PublicError(d)	bug	qError "throw it instead" → unexpected → boundary
throw fail(s, d)	abort	status s + error.tsx chain (blessed)
return fail(s, d)	compat	.value.failed, page renders, status s (deprecated)
throw error(s, d)	abort	deprecated shim → same as throw fail()
return error(s, d)	none	inert value (v1 no-op), undocumented
throw anything else	unexpected	rejection → boundary on read
return plain Error	value	stays a value

Request lifecycle for a guarded inline error (SSR document request):

sequenceDiagram
    participant MW as loadersMiddleware
    participant L as loader fn
    participant SIG as loader signal
    participant C as route component
    MW->>L: settle before streaming (blockSSR default)
    L-->>MW: throws PublicError
    MW->>SIG: record rejection (request-scoped)
    Note over MW: chain continues — no abort,<br/>status stays 200, headers not sent yet
    C->>SIG: .error read (SSR waits for settled state)
    SIG-->>C: the PublicError
    C->>C: early-return guard renders the friendly branch

Loading

• Middleware settle: blockSSR (default) loaders still settle pre-stream. The classifier splits
  rejections: branded fail carrier → rethrow to the chain → serverErrorMiddleware aborts with
  status + error.tsx (today's machinery; status was set at fail() call time); PublicError →
  recorded for the signal, chain continues; unexpected → recorded as internal rejection (boundary
  at render). Redirects still short-circuit.
• The rejection record. Within one request a loader is invoked from two places: the middleware
  settle and the signal compute at render (capture.load()). Success is memoized today; failure
  is erased (delete promises[loaderId]), so under this contract a failed loader would re-run at
  render — double side effects and a nondeterministic page (a decrementStock() loader could fail
  in middleware, then succeed on the re-run). Fix is symmetric memoization in the same
  per-request store: record the settled rejection; load() rethrows it. All the stores live on
  requestEv.sharedMap, which is created per incoming request — so cross-request/cross-user error
  caching is structurally impossible and every retry path (in-loader retries, invalidate(), SPA
  navigation, resubmit) is a fresh request. Record ALL rejections including aborts: the error.tsx
  chain re-render must not re-run the crashed loader.
• error.tsx chain: unchanged mechanism, fed by middleware throw fail()/error() and loader
  abort throws. The error render must not re-run route middleware or the crashed loader (Nuxt
  documents middleware re-execution on its error page as a loop footgun — pinned by test).
  A fail() thrown from a layout loader renders the chain level above the crashed layout
  (pinned by e2e).
• loader.json endpoint (SPA nav), envelope { d | r | e }:
  • inline → {e: PublicError} on HTTP 200 (TypeId keeps instanceof) → client .error,
    SPA-smooth;
  • abort → real status + message; the client renders the route's OWN error.tsx chain (the same
    module SSR renders — SSR/SPA consistent), no reload;
  • unexpected → 500 with no error detail;
  • error/redirect envelopes send Cache-Control: no-store. Today sendLoaderResponse
    applies the loader's maxAge to every envelope, and HTTP 200 is heuristically cacheable with
    no headers at all (RFC 9111) — a CDN could pin one user's error for everyone (the SvelteKit+
    Vercel "SvelteSpill" incident is the real-world instance). Success envelopes keep the existing
    cache policy.
• Client fetch cache: the browser-local fetchCache (per-tab, 5s TTL) caches {e} envelopes
  like any response; invalidate(true) bypasses it — kept as-is.
• blockSSR: false loaders (experimental) cannot abort (stream started): a thrown fail
  carrier reaches the signal, is not a PublicError → unexpected → boundary + dev warn.
• No-boundary escalation stays: unguarded read with no boundary → render rejects → generic
  error page (the existing user-response 500 path).

5.2 Async computeds

Same core semantics as loaders (they share the signal). No fail() in scope — a client-capable
compute cannot abort; its options are PublicError (inline) or unexpected → boundary.

5.3 server$

An imperative RPC (awaited like fetch), not a document render — so no fail(), no error.tsx:

• User throws PublicError → the response is a 200 envelope (distinguishable from a success
  body by shape) carrying the serialized error, with Cache-Control: no-store; the client
  await serverFn() rejects with the inflated PublicError (instanceof holds). Rationale:
  no invented status (the class has none — deliberately), consistency with the loader.json
  envelope, and classification by body shape rather than headers/status (SolidStart's
  header-keyed 200 protocol let infra 500s resolve as success for years). Expected errors are
  business outcomes, not transport failures; unexpected ones keep a real 500.
• Anything else thrown → 500 generic, no detail; internal framework errors (invalid body, …) →
  plain 500.
• Client: a try/catch around the call handles the rejection; an UNHANDLED rejection bubbles via
  the unhandledrejection→qerror bridge to the closest ErrorBoundary around the calling
  component/element.
• The endpoint's error handling is METHOD-AGNOSTIC: classification (PublicError envelope vs 500
  generic) keys on "this is a server-function request", never on the HTTP method — so a future
  transport (e.g. RFC 10008 QUERY for cacheable, safe, body-carrying reads) is a pure addition
  to the method switch and touches zero error paths.

5.4 Actions

• .pending — in-flight until the request returns (was .isRunning).
• .error — a thrown PublicError, LOUD and identical to loaders: .value re-throws it on an
  unguarded read; guard via early return. No per-surface special-casing.
• .formErrors / .fieldErrors — SOFT, value-channel, never gate .value: produced by the
  validator (zod$/valibot$/custom) or manually via a value-returning helper — working name
  invalid({ formErrors, fieldErrors }), the successor to v1's
  return fail(status, {formErrors, fieldErrors}). Value-channel is what keeps them statically
  typeable from the validator/action signature (thrown values cannot contribute to derived
  types — the reason SvelteKit dev-enforces return-only for its form failures).
• .submit — the trigger.
• Dev chooses loud vs soft: throw new PublicError() for a genuine must-handle error;
  validation / "didn't go through, keep the form" → soft channels.
• Open design decision: whether an action settling with .error suppresses loader revalidation
  (React Router uses 2xx-vs-4xx as exactly that switch).

5.5 Middleware / endpoints

• throw fail(status, data) — the blessed abort (via the RequestEventCommon promotion);
  throw error() deprecated, unchanged behavior.
• A PublicError thrown in middleware is UNEXPECTED (redacted generic 500) plus a dev-mode
  warning: "PublicError thrown in middleware has no reader — use fail(status, data) to abort with
  an error page, or throw it from a loader." Middleware has no signal to read the error back from,
  and honoring it would mean silently inventing a status and an abort the developer didn't write.
  Fail-closed, symmetric with the blockSSR:false rule.

6. Status & caching rules

Surface / event	HTTP status	Cache rule
Document, inline loader error (guarded or not)	untouched (200)	normal page caching
Document, throw fail(s) (loader or middleware, pre-stream)	s	error pages: no caching
Document, unexpected with no boundary	500 (generic page; mid-stream: already-sent status)	—
loader.json, success	200 {d}	loader maxAge/eTag policy
loader.json, inline error / redirect	200 {e} / {r}	no-store
loader.json, abort	real status + message	no-store
loader.json, unexpected	500, no detail	no-store
server$, PublicError	200 envelope	no-store
server$, unexpected	500 generic	no-store

Grounding: HTTP 200 is heuristically cacheable by default under RFC 9111 (500/502/503 are not),
so every 200-with-error-payload path must fail closed with explicit no-store. On the SEO side,
Google's soft-404 line matches the model exactly: a 200 page with an inline error notice on real
content is fine (out-of-stock is the canonical example); a 200 page whose content is the error
gets dropped from the index — which is what fail(404) is for. Docs must state this as a hard
rule: not-found main content → fail(404); PublicError is for component-level states.
(Nuxt's opt-in status is the cautionary tale — years of shipped soft-404s.)

The risk class here is mis-selection, not omission: unlike Nuxt (where doing nothing ships the
soft-404 — the error ref auto-populates silently), Qwik has no zero-effort path — expressing an
expected failure requires an explicit throw either way, both options are equally cheap one-liners
in the same loader signature, and an unguarded inline error throws to a boundary instead of
rendering silently. Mis-selection is teachable where omission isn't — which is why the load-bearing
mitigation is placement, not prose: the not-found example in the starters and the first
routeLoader$ docs example must be the fail(404, …) form, with the widget PublicError example
beside it.

7. Security model

• Only PublicError data ever serializes out of an error (its construction is the consent).
  Unexpected errors: never on .error, never serialized (signal state serializes as invalid →
  client recomputes), redacted by the ErrorBoundary membrane when they render a fallback, generic
  500 on transports. Stack traces: dev-only in all serialized forms.
• Abort carriers never serialize (the request ends server-side); their recognition Symbol never
  needs to cross the wire.
• Classification is fail-closed and spoof-resistant: PublicError by TypeId/class + brand;
  the fail carrier by module-private Symbol brand (a foreign {failed: true} object thrown by
  user code is just an unexpected error).

8. Competitive context

How each framework answers the same questions (condensed from the verified research):

Concern	SvelteKit 2	React Router 7/8	TanStack Start	Nuxt 3/4	SolidStart 1.x	Qwik v2 (this design)
Inline expected error (page renders, readable)	None for loads; experimental remote-fn query.error/.loading/.current	None; convention: return data({errors},{status}) as data	None; workaround = TanStack Query .error	useAsyncData → error ref; doc stays 200	Throw → nearest ErrorBoundary fallback; no class	throw new PublicError → .error guard
Abort → error page + status	error(status, body) → nearest +error.svelte	throw data(d,{status}) → nearest route ErrorBoundary	Only notFound()/redirect(); no arbitrary-status abort	throw createError({status}) → single root error.vue	None; compose ErrorBoundary + HttpStatusCode	throw fail(status,d) → error.tsx chain
Unexpected + prod redaction	handleError; {message:'Internal Error'}	Sanitized "Unexpected Server Error", no opt-out	message survives prod; custom fields lost	h3 unhandled flag hides message/data/stack	none — raw message + stack ship in prod	boundary + redaction membrane
Status on loader data error (document)	real status; frozen once streaming	real status (even returned data({status}))	auto 200/404/500 only, undocumented	200 soft-404 trap (years of issues)	200 unless fallback opts in	200 by design; fail() = the status path
SPA-nav error page, no reload	✅ nearest +error.svelte	✅ boundary; real status on .data wire	✅ errorComponent; no status exists	✅ error.vue; no doc status	✅ boundary; RPC stays 200	✅ route's own error.tsx
Middleware throws	error() honored but static fallback page	→ nearest boundary	undocumented; status-setting broken for years	return abortNavigation(err) → error page	return Response only; throws → platform 500	throw fail(); PublicError = unexpected + dev warn
Action soft validation	return fail(status,data) → form prop; return-only, dev-enforced (typing)	return data({errors},{status:400}) → actionData	none in framework (TanStack Form sidecar)	none — userland 422 + error.data	return {error} → submission.result vs throw → submission.error	.formErrors/.fieldErrors soft; .error loud
Server-fn/RPC expected error	remote fns: 200 envelope {type:'error', …}	resource routes: real-status Response	serialized, status ?? 500; message-only prod	$fetch rejects; real status; data payload	200 + X-Error header (proxy-500-as-success bug)	PublicError → 200 envelope + no-store
Return vs throw	strict verbs, dev-errors on wrong verb	verb IS the switch; returned Errors redacted like thrown	parity for redirect only; returned Error → garbage	throw-only convention; "better to throw"	parity for Response helpers only	return = data, throw = control flow; resolved PublicError = dev error
Error class design	classes unexported (instanceof broken) → guards	factories + duck-typed guards; no status class on purpose	no error class at all	NuxtError extends H3Error, data generic + guard	no class; header duck-typing	PublicError<T> extends Error + serdes TypeId + brand

Verdict per dimension — "Leader" counts Qwik as designed here (theoretical direction, not shipped
code):

Dimension	Leader	Verdict
Inline expected errors	Qwik	Only first-class implementation (class + readable channel + serialization contract + loud-when-unguarded). SvelteKit's newest API (remote functions) is converging on the same triple — external validation, not competition, since it doesn't cover loads.
Abort → error page	SvelteKit, narrowly	Same mechanism as fail() → error.tsx (nearest-file hierarchy, real status, SSR+SPA); SvelteKit is ahead on shipped polish and the typed App.Error payload — closable with a typed fail-data interface (App.Error-style augmentation), which is not part of this design.
Unexpected + prod redaction	Qwik	The only model with nested SSR-capable component boundaries AND fail-closed redaction (RR is route-level, Solid leaks in prod, Nuxt has no nested SSR boundary). SvelteKit keeps an observability edge (global handleError hook); this design has no equivalent global hook.
Main-content status defaults (soft-404 risk)	SvelteKit/RR — by restriction	Single-channel frameworks are safe by amputation: every loader failure is an abort, so status-correct is the only path — and the widget case is inexpressible. Among frameworks WITH an inline channel, Qwik leads: no zero-effort path exists (both channels are explicit one-liner throws in the same signature, vs Nuxt's omission trap where doing nothing ships the soft-404), and an unguarded inline error throws instead of rendering silently. Residual risk = mis-selection, owned by docs + starters (§6).
Actions / form validation	SvelteKit (shipped)	Gold standard today (typed form prop, enforced verbs, progressive enhancement). The §5.4 model matches it and adds the loud .error channel SvelteKit lacks.
server$ / RPC errors	Nuxt/h3 on maturity	Mature class + real statuses + redaction flag. Qwik's direction is safest-by-default (envelope + no-store, zero leak surface) but deliberately minimal; a tRPC-style code field is a possible extension, not part of this design.
Return/throw discipline	Tie: SvelteKit = Qwik	Both dev-enforce the verbs; everyone else is convention-or-accident.
Error identity across the wire	Qwik, uniquely	Owning the serializer means instanceof survives resume (own TypeId + brand). RR can't rehydrate custom classes, Solid collapses subclasses, SvelteKit hides its classes — nobody else can offer this.

Overall: Qwik (as designed) > SvelteKit > React Router > Nuxt > SolidStart > TanStack Start — the
differentiator being that all three channels are first-class and symmetric across every surface,
while each competitor is missing at least one channel outright. The §6 soft-404 placement rule is
load-bearing for the status row.

What the survey validates: the readable .error/.pending/.value triple is where the ecosystem
converged (TanStack Query, SWR, Nuxt refs, Next.js "model expected errors as return values", and
SvelteKit's newest API — remote-function query.error/.loading/.current — is the same triple);
class-based safe-by-contract classification is universal; soft validation on the value channel is
unanimous; keeping route-level error pages (error.tsx) and component boundaries (ErrorBoundary)
as distinct mechanisms matches the strongest designs. Qwik is differentiated by having all three
channels as first-class, symmetric APIs — every other framework is missing at least one (see the
first column of gaps) or leaks in prod.

9. Compatibility & migration

Concern	v1 (qwik-city)	v2 (this design)	v3
Inline user-friendly error	return fail(s, d) → .value.failed	throw new PublicError(data) → .error guard; return fail() deprecated	PublicError only
Abort a page → error.tsx	throw error(status, data) (also undocumented throw fail())	throw fail(status, data); throw error() deprecated shim	throw fail() only
Unexpected error	aborts request → generic 500	closest ErrorBoundary (never route-scoped — the framework can't know main-content-vs-widget; main content escalates via try/catch → throw fail())	same

API	Status	Notes
PublicError (core class)	NEW	inline channel; free import, usable anywhere; throw-only
.error read channel	NEW (blessed)	loaders / async computeds / actions
.pending	NEW (rename)	replaces .loading (and action .isRunning)
ErrorBoundary	NEW	catches unexpected + unguarded reads
fail()	MODIFIED	promoted to RequestEventCommon; throw = abort (blessed); return = .value.failed (deprecated)
error.tsx	MODIFIED	same file; fail()-triggered; renders on SSR and SPA nav
error()	DEPRECATED	shim producing the fail carrier → "throw fail(status, data)"
ServerError	REMOVED	breaking (was v2-beta-only); migration: → throw fail(status, data)

Deprecation-message coherence: error() → "throw fail(status, data)"; fail() return-form /
.value.failed → "throw new PublicError(data)". Release impact: @qwik.dev/core minor
(PublicError + read semantics + rename); @qwik.dev/router major (ServerError removal + fail
promotion + abort recognition).

Docs must carry, verbatim-level: the one-sentence model ("throw new PublicError(data) for
user-friendly errors anywhere → .error or closest ErrorBoundary; throw fail(status, data) in a
loader/middleware to abort the page with a status + error.tsx"), the soft-404 rule (§6), and the
try/catch trap ("don't wrap throw fail() in your own try/catch — a swallowed abort renders a
confusing success"; same for accidentally catching PublicError before the framework sees it).

---

Test specs (no bodies)

A. Core unit — async-signal.unit.tsx

• A1 .error read triggers computation (no prior reads)
• A2 server: .error read while computing throws the pending compute promise
• A3 client: .error read while computing returns undefined; error effects fire on settle
• A4 compute throws PublicError → .error returns it; .value read THROWS it; .pending false
  (pin: .loading gone, .pending present)
• A5 compute throws plain Error → .error undefined; .value read throws it → boundary
• A6 compute RESOLVES with a PublicError instance → qError ("throw it instead") on the unexpected
  channel; returned plain Error stays a value
• A7 DOM AbortError still ignored as cancellation (no channel written)
• A8 .value setter clears inline AND unexpected state
• A9 invalidate + successful recompute clears .error
• A10 timeout error lands in the unexpected channel
• A11 type pin: .error is PublicError | undefined
• A12 classification accepts a brand-marked PublicError from a foreign module copy
  (package-duplication guard)

B. Core spec — use-computed.spec.tsx (SSR harness + resume)

• B1 SSR: .error-guarded component renders the friendly branch on PublicError
• B2 SSR: guard falls through on success → value renders (regression)
• B3 SSR: unguarded .value + PublicError + boundary → closest fallback renders
• B4 SSR: unguarded .value + unexpected + boundary → fallback renders (existing, keep)
• B5 SSR: guarded component + unexpected error → guard sees undefined, .value throws → boundary
  fallback (not the friendly branch)
• B6 SSR: wrapped-signal read position (<p>{sig.value.x}</p>) errors → boundary via the
  MaybeAsyncSignal path
• B7 resume: SSR-serialized public error → client .error returns PublicError (instanceof holds)
• B8 CSR: late-arriving public error re-renders the guard branch (error effects)
• B9 SSR: no boundary + unexpected → render rejects (escalation pin, if harness allows)
• B10 async computed throws a fail() carrier → unexpected (boundary, not .error) + dev warn

C. Serdes — serdes.unit.ts

• C1 PublicError round-trip: instanceof + message + data; stack dev-only
• C2 AsyncSignal with public error: error state round-trips, .error readable after inflate
• C3 AsyncSignal with unexpected rejection: serializes WITHOUT the error (invalid → recompute);
  unexpected message text absent from serialized output (leak pin)
• C4 the fail carrier does NOT inflate as PublicError and never reaches .error
  (classification integrity — negative pin)
• C5 fail carrier (Error subclass) round-trips .value.failed === true + data keys
  (return fail() compat after resume)

D. Router unit — loaders middleware / route-loaders / server$

• D1 blockSSR loader throwing PublicError does NOT reject the middleware chain / abort the request
• D2 rejected loader is not re-executed when the signal computes (single-execution; incl.
  error.tsx re-render after an abort)
• D3 response status stays 200 for a thrown loader PublicError
• D4 loader redirect still short-circuits (regression)
• D5 return fail() → .value.failed + response status set, page renders, .error undefined
  (deprecated pin)
• D6 unexpected loader error: no middleware abort; signal rejects; single execution
• D7 loader.json endpoint: inline → {e} envelope HTTP 200 (instanceof after deserialize);
  abort throw → real status response; unexpected → 500 without error detail
• D8 serverErrorMiddleware renders the error.tsx chain for middleware-thrown fail()/error();
  the error render re-runs neither route middleware nor the crashed loader
• D9 rejection record is request-scoped: a second request re-runs the loader (fresh sharedMap)
• D10 API pins: fail on RequestEventCommon but NOT a free export and NOT on component/client
  types; error() @deprecated returning the fail carrier; ServerError import is a compile
  error; PublicError exported from core
• D11 loader throw fail(status, d) → abort: status + error page (blessed pin)
• D12 loader throw error(status, d) (deprecated shim) → still aborts
• D13 loader return fail() → .value.failed (v1 compat). return error() → inert value
  (v1 no-op) — unsupported, not a pin
• D14 blockSSR:false loader throwing fail() → unexpected (boundary) + dev warn; no abort
• D15 middleware handler throw fail(status, d) → abort (via the Common promotion)
• D16 action RETURNS fail() → validation data (.value.failed), never abort (carrier stays out of
  throwIfControlFlowSignal)
• D17 server$: throw new PublicError(d) → 200 error envelope + no-store; client await rejects
  with the inflated instance; unhandled → closest ErrorBoundary (qerror bridge); try/catch
  handles it. Unexpected throw → 500 generic → boundary
• D18 fail carrier: primitive message string-wraps to {message} (no char-spread); carrier embeds
  status; getErrorHtml + serverErrorMiddleware read .message not .data
• D19 malformed-URL 404 completion stays a bare post-headers object — NOT ev.fail() (check()
  hazard pin); still renders the 404 page
• D20 fail carrier is an Error subclass: instanceof Error, has a stack, .value.failed +
  spread-data reads unchanged (compat pin)
• D21 a thrown plain {failed: true} object (no brand) → UNEXPECTED, not an abort (spoof pin)
• D22 middleware handler throwing PublicError → generic 500 + dev warning naming fail()
• D23 loader.json error/redirect envelopes send Cache-Control: no-store (success keeps the
  loader cache policy); server$ error responses send no-store

E. Router e2e (qwikrouter-test app)

• E1 SSR: loader throws PublicError → route renders .error branch, HTTP 200
• E2 SSR: loader RESOLVES with a PublicError instance → dev error → boundary/escalation
  (not .error)
• E3 SSR: unexpected loader error + boundary in route → fallback renders
• E4 SSR: unexpected loader error, no boundary → generic error response (escalation pin)
• E5 SPA nav: loader errors publicly → .error branch renders client-side (envelope +
  instanceof); the {e} response carries no-store
• E6 SPA nav: unexpected loader error → boundary fallback client-side
• E7 prod app (qDev=false): unexpected message absent from HTML/state; public data present
  (redaction pin)
• E8 SSR: loader throws fail() → HTTP status + error page (replaces the returned-control-flow
  pin: return error(401) no longer aborts — the fixture becomes throw fail(401, {message}))
• E9 SPA nav to a loader that throw fail()s → client renders the route's already-resolved
  error.tsx chain (same module SSR renders), passing the fail status/message; no reload.
  Direct load / refresh → SSR error.tsx with the real status
• E10 SSR: middleware handler throws fail() → HTTP status + error page (deprecated error() covered
  by existing e2e, stays green)
• E11 fail() thrown from a LAYOUT loader → the error.tsx level above the crashed layout renders
  (chain-resolution pin)

F. Actions (the §5.4 surface)

• F1 action throws PublicError → .error set; unguarded .value read re-throws → closest
  boundary (identical gating to loaders)
• F2 .error guard renders the inline branch; the form stays rendered and resubmittable
• F3 validator failure → .fieldErrors/.formErrors populated; .value NOT gated;
  .error undefined (soft channels never gate)
• F4 manual return invalid({ formErrors, fieldErrors }) → soft channels populated, statically
  typed from the action signature
• F5 unexpected action throw → .submit() rejects; unhandled → closest boundary; redacted in prod
• F6 .pending true while submitting, false after settle (pin: .isRunning gone)
• F7 action return fail() → .value.failed compat, never abort (pairs with D16)

[maiieul]

Update (2026-08-04): the converged v2 error design drops PublicError. Server-origin failures always redact in production — generic message + digest; the original stays server-side (onError$, logs). Client-origin errors render as thrown, since their messages already live in the browser bundle. Server-authored displayable content moves to outcomes (httpError(), invalid()) or typed returns.

Landed on the #8745 branch: the class and its serdes are removed, redaction is now origin-based, and pages whose boundary caught before the first flush — plus error documents — send Cache-Control: no-store.