A deferred region of a streamed route fails after the shell was flushed. What reaches the browser, and what does the page report?

## Where the failure lands A deferred region's work runs after the shell has been flushed, which puts it below the response's commit point. Two things follow immediately, and candidates who have not lived through this usually miss both: - **The status is settled.** Whatever the shell committed — almost always a success status — is what this request will be recorded as, no matter what happens next. - **The document is unreplaceable.** The browser has already parsed a frame, applied styles, possibly run scripts. A whole-page error screen would have to take the place of markup the user is looking at; the response has no mechanism for that. So the framework's only remaining channel is the same one it uses for success: another chunk on the open response. ## What the framework actually sends 1. The failed region's placeholder is targeted exactly as a successful one would be. 2. In place of the finished markup, the chunk carries the **nearest error fallback** declared around that region — a scoped error UI, an empty state, or a retry affordance. 3. If no fallback is declared around it, the behaviour varies: some frameworks fall back to a generic in-region message, some leave the loading fallback on screen indefinitely, and some abort the response. 4. Other pending regions are unaffected and keep arriving; a failure in one placeholder is not a failure of the document. | what failed | what the client gets | status on the wire | |---|---|---| | a level above the flush | the route's whole-page error screen, or an error status | error status, chosen before commit | | a deferred region with a fallback around it | that fallback swapped into the placeholder | the success already committed | | a deferred region with no fallback | framework-dependent: a generic message, a stuck placeholder, or a truncated response | the success already committed | | the write itself, mid-stream | a truncated document, pending placeholders stuck | the success already committed | ## The asymmetry that surprises people The same exception thrown one level higher in the same route produces a completely different outcome: above the flush, the framework's error handling can still choose the status and render the whole-page error screen; below it, the identical failure is a cosmetic swap inside one box on an otherwise successful page. Nothing about the exception changed — only where in the chain it was raised relative to the flush. That is worth saying out loud in an interview, because it is the practical reason to be deliberate about what gets deferred. ## The truncated-response case The worse outcome is not an error fallback but no more bytes. If the failure prevents the server from writing anything further — the process dies, the connection is severed, a write times out — the response simply ends in the middle of a document. The browser has no way to distinguish that from a slow network that stopped: it keeps the partial page, the pending placeholders keep their loading fallbacks, and nothing ever resolves them. There is no error page, because the response reported success long ago. Recovery has to come from the client or from the user. This is the case worth designing against: a per-region fallback is a degraded page, while a truncated stream is a page frozen mid-load with no signal that anything went wrong. ## What the page should do about it - **Declare a fallback around every deferred region**, so the framework has somewhere to put a failure instead of choosing for you. - **Make the fallback actionable** when the region is a read — a retry control that re-requests just that region's data is cheap, and far better than asking the user to reload a page whose good parts are already correct. - **Do not defer work whose failure should have been the whole answer.** If a region failing means the page is meaningless, that work belonged above the flush where a failure could still become an error status. - **Accept that the user's judgement differs from the status code's.** The page reports success and shows a broken panel; whether that is acceptable is a product decision per region, and it is the reason some regions are held in the shell. ## Where meta-frameworks differ The fallback scoping model is not uniform: some frameworks resolve a failure to the nearest enclosing error boundary and will walk outwards if none is declared, others scope strictly to the deferred region, and a few end the response rather than guess. Confirm the behaviour for the route you own rather than assuming the shape — the difference shows up only when something fails in production.