feat(core): core ErrorBoundary in SSR and CSR

[maiieul]

What is it?

• Feature / enhancement

Description

Moves ErrorBoundary from @qwik.dev/router to @qwik.dev/core so it ships with the framework, and makes it the single error-boundary surface.

ErrorBoundary — design & mechanism

<ErrorBoundary> in @qwik.dev/core. Experimental: gated on the errorBoundary Vite flag (the component throws a clear error with the flag off). Works in in-order and out-of-order streaming SSR, CSR, and resumed CSR.

Public API

// @qwik.dev/core
export interface ErrorBoundaryProps {
  /** REQUIRED. Lazily loaded — only fetched when the subtree errors. Receives an `Error`
   *  (`{error.message}` is always safe): a non-Error throw is wrapped, and prod redacts to a
   *  generic message + `digest`. */
  fallback$: QRL<(error: Error, reset: QRL<() => void>) => JSXOutput>;
  /** Telemetry side-effect; never affects rendering. Receives the original `Error` instance;
   *  a non-Error throw arrives wrapped in an `Error` whose `cause` is the raw value.
   *  `info` carries `phase` + `boundaryId`. */
  onError$?: QRL<(error: Error, info: ErrorBoundaryInfo) => void>;
}
export const ErrorBoundary: Component<ErrorBoundaryProps>;

// Server-only redaction override on RenderOptions (renderToStream / renderToString):
transformError?: (error: unknown) => unknown;

<ErrorBoundary
  fallback$={(error, reset) => (
    <div role="alert">
      <p>Something broke: {error.message}</p>
      {/* wrap as `() => reset()` — a bare QRL doesn't serialize the listener on a streamed fallback */}
      <button onClick$={() => reset()}>Try again</button>
    </div>
  )}
  onError$={(error, info) => reportToSentry(error, info.phase)}
>
  <Dashboard />
</ErrorBoundary>

1. Invariant: never block streaming

A boundary may sit anywhere, including the root, at ~zero cost — it never buffers its content. Content streams live into a content-host; on a throw the SSR catch only sets store.error (a redacted projection), fires onError$, marks the dead content inert, and returns null — a sibling fallback-host delivers the fallback. A swap, never a buffer-rollback. The closest boundary catches.

2. The swap: decided by error origin, at drain time

The fallback host picks its mechanism when it drains (SSRErrorFallbackHost) — by which point any in-place throw has already set store.error:

• In-place errors (sync render, awaited async, rejected promise child, async signal, task) render the fallback inline and swap with a tiny qErr(id) display toggle (q:ebf host) — regardless of the streaming mode.
• No error yet under out-of-order streaming → a q:rp late-delivery shell. A genuinely deferred throw from a child <Suspense> (the boundary's position already flushed) tears the whole boundary down and streams the fallback late as a qO segment.
• A boundary inside a Suspense segment renders inline with a hoisted qErr emitted after the segment reveal.

So a boundary without <Suspense> involvement never uses qO: the happy path ships no swap scripts at all, and errors swap in document order via qErr. (Under out-of-order mode an error-free boundary still emits its passive q:rp shell markers.) The deferred path stays segment-shaped because its vnode-data must travel through the segment to stay resume-consistent (inline content must never sit under a q:rp host).

3. Production redaction & the Error membrane

In prod, a caught error is serialized to the client as a generic message + stable digest (message, stack, and attached props stripped); dev keeps full fidelity. RenderOptions.transformError overrides the projection, fail-closed: a throwing or non-serializable transform falls back to the generic scrub, never the raw error. onError$ always receives the original error — only the client-bound payload (and what fallback$ displays) is redacted. The client-side display path applies the same redaction for parity.

Both callbacks are typed Error, and the runtime guarantees it rather than asserting it: a non-Error throw is coerced to an Error. For onError$ (telemetry) the raw thrown value is preserved on error.cause; for the prod-redacted store.error (which is serialized into the HTML) the cause is never attached — that would be a data-leak channel. So {error.message} is always safe, and the raw value survives only where it never serializes (onError$ + server logError).

4. What routes to a boundary

Render throws (sync + async), useTask$/useVisibleTask$ throws, event-handler throws (qwikloader emits qerror → nearest boundary, info.phase === 'event'), async-generator and async-signal rejections. Thrown falsy values — including undefined — reveal the fallback (normalized to a keyable Error; onError$ still gets the raw value). A fallback chunk that fails to load renders a built-in role="alert" last-resort node; a fallback that loads and then throws escalates to the ancestor boundary. Fire-and-forget rejections hit a single page-level unhandledrejection bridge (logged, not bounded). No enclosing boundary → the original error surfaces (SSR rejects the render; CSR logs and async-rethrows so window.onerror/monitoring fires).

5. Resume, not re-run

store.error serializes, so a server-errored boundary resumes already showing its fallback without re-running component code; a later client error routes to the same boundary. The swapped-out content is torn down inert (INERT vnode-data, cleared effects, cut slot refs; serialized refs into the inert region are written as undefined), so it can never resume — including nested boundaries where the outer and inner both errored on the server.

6. Routing & escalation

Layout	Catches	Untouched
EB-outer › Suspense › EB-inner › throw	EB-inner	EB-outer
EB-outer › Suspense › throw (no inner EB)	EB-outer	—
EB-outer › Suspense-A › EB-mid › Suspense-B › throw	EB-mid	EB-outer

A throwing fallback escalates to the nearest ancestor (no loop). onError$ fires once per caught error (a new error caught on the server re-fires with it; a second client error escalates to the ancestor instead), swallows its own throws, and never affects rendering.

7. reset()

The second fallback$ arg: clears the error and re-executes the children, re-running their async work. Works for client-caught and SSR errors, in-order and out-of-order, on resumed pages, and for boundaries inside <Suspense>.

Architecture diagrams (under the hood)

Component structure — the boundary emits two sibling hosts; which one shows is a pure function of one serialized field, store.error.

flowchart TD
  EB["ErrorBoundary { fallback$, onError$ }"] --> CMP["errorBoundaryCmp (server)"]
  CMP --> H1["content-host: div q:ebc=id<br/>style = fnSignal(store) → display none/contents<br/>holds a Slot = your children"]
  CMP --> H2["SSRErrorFallbackHost<br/>internal server component<br/>picks fallback delivery at DRAIN time"]
  CMP -. writes .-> STORE["ErrorBoundaryStore<br/>error? — the SSR→CSR bridge, redacted<br/>boundaryId, resetOwner (serialized node ref)<br/>$fallback$, $onError$ — noSerialize mirrors"]

Loading

SSR: catching a throw and choosing delivery — the handler only marks state and returns null; the fallback host picks qErr (in-place) vs qO (deferred) at drain time.

flowchart TD
  START["SSR drain reaches a node under the boundary"] --> THROW{"throws?"}
  THROW -- no --> OK["stream normally; content-host style stays contents"]
  THROW -- yes --> CATCH["catchToErrorBoundary → renderErrorBoundaryFallback"]
  CATCH --> FIND["findErrorBoundaryNode: nearest boundary<br/>whose $fallback$ is still attached"]
  FIND -- none --> RETHROW["rethrow → abort render"]
  FIND -- found --> MARK["markBoundaryErrored: store.error = redacted;<br/>fireOnError once"]
  MARK --> INERT["markSubtreeInert: tag INERT, clearAllEffects,<br/>cut claimed-Slot ref"]
  INERT --> NULL["return null"]
  NULL --> HOST["later: SSRErrorFallbackHost drains"]
  HOST --> DEC{"deliverLate? OOOS active & not in a segment & no error yet"}
  DEC -- "no — in place" --> INLINE["host q:ebf + inline fallback + qErr(id) swap"]
  DEC -- "yes — deferred" --> LATE["host q:rp + placeholder;<br/>fallback streamed later as a qO segment"]

Loading

Resume and the swap — the inline qErr script swaps hosts before resume (no flash); the reactive style then takes over.

sequenceDiagram
  participant B as Browser parser
  participant S as Inline qErr script
  participant Q as Qwik resume
  B->>B: parse content-host (q:ebc) + partial content
  B->>B: parse fallback-host (q:ebf) + fallback markup
  B->>S: qErr(id) runs, scoped by currentScript.closest(container)
  S->>S: content-host display:none, fallback-host display:contents
  Note over S: swap done pre-resume — no flash
  B->>Q: qwik/state at stream end triggers resume
  Q->>Q: deserialize store.error (redacted Error)
  Q->>Q: reactive style fnSignal(store) now owns the toggle
  Q->>Q: fallback resumable — interactive on first click

Loading

Client-time errors & escalation — everything funnels through handleError, which walks up ERROR_CONTEXT.

flowchart TD
  SRC["render throw / task / signal / qerror event / visible-task"] --> HE["handleError(err, host, phase)"]
  HE --> WALK["walk up ERROR_CONTEXT from host"]
  WALK --> B{"boundary?"}
  B -- "none left" --> GLOBAL["logErrorAndThrowAsync → window.onerror"]
  B -- "store.error === undefined" --> CATCH["store.error = err; fireOnError(props.onError$);<br/>markVNodeDirty → render fallback"]
  B -- "already errored/dirty" --> ESC["escalate to parent boundary"]
  ESC --> WALK

Loading

reset() — dirtying the owner in the same tick as clearing the error re-supplies and re-executes the consumed children.

sequenceDiagram
  participant U as User clicks Retry
  participant R as reset QRL (_ebR, host captured)
  participant C as resetErrorBoundary(host)
  U->>R: onClick$ = () => reset()
  R->>C: resolve boundary (ERROR_CONTEXT, else closest q:ebf/q:rp/q:ebc)
  C->>C: resolve owner (getParentHost, climb past Suspense, else serialized resetOwner)
  C->>C: markVNodeDirty(owner) + store.error = undefined, same tick
  C->>C: owner re-renders, re-distributes fresh children into Slot
  Note over C: error cleared, boundary renders Slot, children RE-EXECUTE

Loading

The Error / redaction membrane — two channels, two jobs: telemetry gets the truth, display gets something always-safe (and prod-serialized state never carries the raw value).

flowchart TD
  THROWN["thrown value: Error | 0 | '' | undefined | object"] --> SPLIT{"which channel?"}
  SPLIT -- "onError$ (telemetry)" --> OE["toBoundaryError(raw, cause=true):<br/>Error → same instance; non-Error → Error(String(raw)), cause=raw"]
  SPLIT -- "server logError" --> LOG["always the RAW original"]
  SPLIT -- "store.error → fallback$ (display)" --> ENV{"dev or prod?"}
  ENV -- dev --> K{"keepable?"}
  K -- "Error" --> RAW["pass untouched (enumerable fields serialize)"]
  K -- "serializable non-Error" --> W["Error(String(raw)), cause=raw"]
  K -- "non-serializable" --> WN["Error(message), no cause"]
  ENV -- prod --> RED["redactToGeneric: fresh Error + digest<br/>NEVER cause, NEVER fields (serialized-leak guard)"]

Loading

Also in this PR

• Suspense deferral through an intervening component (own changeset): a component sitting between a <Suspense> and its suspending child no longer blocks deferral (found via EB, Suspense-generic; regression-tested with a plain stateful wrapper).
• Extracted to standalone PRs, kept here until the next build/v2 sync dedupes them: fix(qwik): emit backpatch entries in document order for the forward-only executor #8790 (backpatch document-order), test(qwik): fix stop-propagation in the events e2e fixture and pin deferred-handler loader behavior #8791 (events fixture + loader behavior tests).

Tests

Unit (146 specs) — behavior describe.each across CSR/SSR, a 3-arm reset table (CSR click / resumed in-order / resumed OOOS), CSR-specific (qerror routing + nearest-container isolation, falsy values incl. undefined, multi-container, last-resort, unhandledrejection bridge), SSR-specific (safety net, async-generator, non-serializable), SSR→CSR cross-phase (resume, inert drop, post-resume errors), qErr swap mechanics (incl. in-place-beside-a-live-segment), OOOS/Suspense suite (case b/c, routing, concurrent teardown), and redaction + transformError + the Error-coercion contract (identity, cause, prod no-cause/no-fields).

E2E (35 real-browser tests) — streaming swaps in-order + OOOS and interactivity after resume, deferred teardown, inert content never re-runs, client-time errors after resume, escalation incl. throwing fallbacks (both modes), reset() (7 scenarios), onError$ fires once, no-boundary surfacing, nested both-error resume, and a dedicated qDev=false prod app pinning client-side redaction display + prod resume + reset round-trip.

[changeset-bot]

🦋 Changeset detected

Latest commit: 58094a9

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 6 packages

Name	Type
@qwik.dev/devtools	Minor
@qwik.dev/core	Major
@qwik.dev/router	Major
eslint-plugin-qwik	Major
@qwik.dev/react	Major
create-qwik	Major

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

@qwik.dev/core

npm i https://pkg.pr.new/QwikDev/qwik/@qwik.dev/core@8745

@qwik.dev/router

npm i https://pkg.pr.new/QwikDev/qwik/@qwik.dev/router@8745

eslint-plugin-qwik

npm i https://pkg.pr.new/QwikDev/qwik/eslint-plugin-qwik@8745

create-qwik

npm i https://pkg.pr.new/QwikDev/qwik/create-qwik@8745

@qwik.dev/optimizer

npm i https://pkg.pr.new/QwikDev/qwik/@qwik.dev/optimizer@8745

@qwik.dev/devtools

npm i https://pkg.pr.new/QwikDev/qwik/@qwik.dev/devtools@8745

commit: 58094a9

[github-actions]

built with Refined Cloudflare Pages Action

⚡ Cloudflare Pages Deployment

Name	Status	Preview	Last Commit
qwik-docs	✅ Ready (View Log)	Visit Preview	58094a9