0058. <boundary> catches failures, and shows its <fallback> with a retry
- Status: Accepted (Mik, 17 Nov 2026)
- Date: 2026-11-14
- Decided by: integrator (internal only), pending Mik's approval
- Planning item: none (WP12)
Context
One component that throws while it mounts, or while a binding updates, used to break the screen: the rest of the build stopped, or the reaction batch stopped part way. An app should show what failed, keep everything else working, and let the user try again.
Decision
<boundary> is control flow (it is no view of its own). Its children are its content; a <fallback> directly inside it is what it shows when the content fails:
<boundary>
<Chart data={sales} />
<fallback as="failure">
<text>{failure.message}</text>
<button on:press={failure.retry}>Try again</button>
</fallback>
</boundary>
- A throw while the content is built (a component's script, an expression) or while any of its bindings updates, however much later, goes to the nearest boundary around it, which shows its fallback in place of the content. The rest of the screen carries on.
asnames the failure for the fallback's expressions, as a list names its item:failure.messageis a sentence,failure.errorwhat was thrown, andfailure.retry()builds the content again.- Without a fallback, a boundary shows "Something went wrong here." and a Try again button.
- Throws in event handlers are not caught: they are not part of mounting or updating, and the handler's own code should handle them. Throws inside a component's own
effect(...)are not caught yet either. - A fallback outside a boundary is E0242; a second fallback is E0243.
Every island (decision 0057) is a boundary with the default fallback.
Native (updated): built in the engine adapter (packages/engine/src/boundary.tsx), which catches what the content throws while it is built or drawn again and shows the same fallback, with failure.retry().
Alternatives considered
| Option | Why not |
|---|---|
A <piece name="fallback"> | Pieces fill a component's slots; a boundary is not a component |
<boundary> followed by <catch>, like <show> and <otherwise> | The fallback belongs to the boundary; inside it, it is clear which one it stands in for |
A retry attribute on a button | failure.retry is an ordinary function, usable from any handler, as in the example's "Fix and try again" |
Consequences
The web mount runs every binding inside the boundary current when it was made. Outside every boundary nothing changes.