Suspense and error boundaries: what waits and what fails together

A play runs on a stage split into sections, each with its own curtain. The stage manager opens a section only when every set piece behind that curtain is in place.

In the analogy	In React
A section's curtain stays shut until every piece behind it is set	A <Suspense> boundary shows its fallback until every descendant is ready
While it is shut, the audience sees only the curtain, not the pieces already set	The fallback replaces the whole subtree, ready siblings included
Sections with no shut curtain play on	Content outside the boundary commits
Where the curtains hang decides what the audience waits for together	Boundary placement decides what loads together
Mid-show, the manager keeps the current scene lit until the next one is fully set	startTransition keeps the old UI while the new one suspends
A set collapses in one section: that curtain closes behind a "scene unavailable" card, and the show goes on	An error boundary shows its fallback for its own subtree only
A spill in the lobby is front-of-house's job, not a stage incident	Event-handler and timer errors are not render errors; the boundary never sees them

Breaks down when:

• Crews build sets in parallel; a child component cannot start its fetch until its parent gets past use(). Wrong inference: "nested components load in parallel."
• A curtain can be half drawn; a fallback is all or nothing. Wrong inference: "the ready half of the subtree shows early."
• A half-built set survives the wait; a subtree that suspended before mounting keeps no state. Wrong inference: "its state is kept."

Contrasting case: a component that fetches in useEffect and shows its own "Loading…" flag. No boundary is involved: Suspense does not detect fetches in effects or event handlers.

In real terms: use() or lazy suspends a component, the closest <Suspense> renders its fallback for its whole subtree, and an error boundary does the same for errors thrown while rendering its subtree.

Example 1: ExamHall EXH-457, "one broken chart question blanks the whole paper"

Q3's chart data arrives as null, so QuestionWidget throws a TypeError while rendering.

no boundary: (blank)
one boundary around the paper: ECON-201 | Exam unavailable
one boundary per question (MR !781): ECON-201 | Q1 chart: 1,2 | Q2 chart: 3 | Q3: could not load, tell your proctor | Q4 chart: 4

With no boundary, React removes the whole UI. One boundary around the paper keeps the header but loses every question. A boundary per question loses only Q3 (steps 8, 3).

Example 2: what an error boundary catches

Each case throws once inside <ErrorBoundary><Widget/></ErrorBoundary>:

render                      fallback shown: yes | caught by a boundary: boom in render
useEffect                   fallback shown: yes | caught by a boundary: boom in useEffect
componentDidMount           fallback shown: yes | caught by a boundary: boom in componentDidMount
use(rejected promise)       fallback shown: yes | caught by a boundary: boom in rejected promise
lazy() load rejects         fallback shown: yes | caught by a boundary: boom in lazy load
onClick handler             fallback shown: no  | screen: widget ok | window error: boom in onClick
setTimeout callback         fallback shown: no  | screen: widget ok | uncaught exception (process): boom in setTimeout
useTransition start()       fallback shown: yes | caught by a boundary: boom in useTransition start
standalone startTransition  fallback shown: no  | screen: widget ok | window error: boom in standalone startTransition

A rejected use() promise or lazy load goes to the error boundary, not the Suspense fallback. Handler and timer errors leave the widget on screen, and so does a throw inside the standalone startTransition; only useTransition's version reaches the boundary (step 9). react.dev documents render errors; the effect and lifecycle rows were observed in React 19.3, and only the legacy docs name lifecycle methods.

Example 3: ExamHall, moving to a section that is still loading

Section reads a cached per-section promise with use(); Section B's promise is pending.

[plain setSection] B pending:        Next section | Loading section…
[startTransition] B pending:        Next section (loading…) | A1 Demand
[startTransition] B resolved:       Next section | B1 Tariffs, B2 Quotas

A plain update hides Section A behind the fallback. A Transition from useTransition keeps Section A up, and its isPending is true meanwhile (step 7).