Skip to content
fa
Search Frontend Atlas
Search questions and concepts across the handbook.
Performance & Reliabilityadvanced14 min read

How should error boundaries, global handlers, and toasts work together?

Separate render errors, async failures, and user-facing messages so failures are recoverable and debuggable without fighting each other.

Useful prerequisites

An error in one part of an application does not always need to take down the whole page. A failed image, a rejected request and a render-time exception have different recovery options. Good error handling starts by deciding where each failure should appear and what the user can do next.

An error in one part of an application does not always need to take down the whole page. A failed image, a rejected request and a render-time exception have different recovery options. Good error handling starts by deciding where each failure should appear and what the user can do next.

The quick version

Treat different failure kinds as different surfaces. Error boundaries catch render-time failures in the component tree and let you show a fallback UI. Global handlers catch uncaught async errors and crashes that escape the tree. Toasts and inline messages are for recoverable, user-facing problems that should not unmount whole sections of the page. Wire them so they do not double-report, swallow each other, or leave the app in a dead state.

Build the mental model

A render error, a failed network request, and a validation message are not the same thing:

  • Render errors (thrown while rendering, constructing, or running framework-managed lifecycle code) can leave the tree in an inconsistent state. Boundaries exist to isolate that damage and show a fallback. Exact capture rules vary by framework; ordinary event-handler and later async failures need explicit handling.
  • Async failures (rejected promises, failed fetches, background task errors) do not automatically trigger render error boundaries in most frameworks. They need explicit handling or a global listener.
  • User-recoverable problems (wrong password, rate limit, “save failed — retry?”) should usually stay in the UI the user is already looking at, not replace the whole page with an error boundary fallback.

If you route everything through a single toast or a single top-level boundary, you either over-react (full-page error for a failed auto-save) or under-react (a silent failure the user never sees).

Error boundaries — what they are good for

Use them to isolate parts of the tree that can fail independently:

  • A widget that depends on third-party data.
  • A complex visualisation that might throw on bad input.
  • A route-level section where a failure should not take down the shell (nav, chrome, other columns).

A good boundary:

  • Shows a clear fallback (message + retry if it makes sense).
  • Reports the error to your observability tool.
  • Does not try to “handle” ordinary business failures (those belong closer to the action that failed).

Boundaries do not catch:

  • Errors in event handlers (unless you rethrow or handle them).
  • Async code that fails after the render phase.
  • Errors outside their subtree.

So they are necessary, not sufficient.

Global handlers — the safety net

window.onerror, unhandledrejection, and framework-level global error hooks catch what escapes everything else. Their job is:

  1. Report to observability (with enough context to debug).
  2. Optionally show a last-resort UI (“Something went wrong — reload”) if the app is no longer trustworthy.
  3. Avoid double-reporting errors that were already handled and reported closer to the source.

They should stay thin. Putting product logic or complex recovery in the global handler usually creates hard-to-test paths and surprising behaviour.

Toasts and inline errors — the recoverable path

For failures the user can act on:

  • Prefer inline errors next to the form, the list, or the action that failed. They keep context.
  • Use toasts / banners for transient, cross-cutting messages (“Saved”, “Connection restored”, “Could not sync — retrying”).
  • Avoid toasts as the only signal for errors that leave the UI in a wrong state. If the save failed, the form should still show that it is dirty or that the last save did not land.

Policy tips that reduce noise:

  • Do not toast every network failure if the inline UI already explains it.
  • Do not toast and also replace the page with a boundary for the same error.
  • Deduplicate identical messages in a short time window so retries do not spam the user.

A practical layering

1. Action-level handling
   - try/catch around the request
   - map known failures to field/form errors or a local message
   - report unexpected failures to observability

2. Route / section error boundary
   - catch render failures in this section
   - fallback UI + report

3. App shell boundary
   - last isolation for the main content
   - keep chrome usable if possible

4. Global handlers
   - uncaught exceptions and rejections
   - report + last-resort UI if needed

Each layer should know what it is responsible for and what it should leave alone.

See it in code

async function saveProfile(input: ProfileInput) {
  try {
    await api.updateProfile(input);
    showToast({ kind: 'success', message: 'Profile saved' });
  } catch (error) {
    if (isValidationError(error)) {
      setFieldErrors(error.fields);
      return;
    }

    reportError(error, { action: 'profile.save' });
    setFormMessage('We could not save your changes. Try again.');
  }
}

The action handles expected, recoverable failures close to their source. A render error in the surrounding profile panel belongs to an error boundary; an uncaught rejection belongs to the global safety net. Do not throw an ordinary validation or network failure just to route it through a boundary.

Where it gets tricky

Errors during render of the fallback itself.
A buggy error boundary can take down more of the tree. Keep fallbacks simple and defensive.

Optimistic UI + failure.
If you optimistically updated and the request fails, the error surface is part of the rollback story. A toast alone is not enough if the UI still shows the optimistic state.

Concurrent features / multiple roots.
Some frameworks have multiple independent trees. Make sure boundaries and reporting are attached where failures can actually surface.

Third-party scripts.
They can throw into the global scope. Decide whether you report them at the same severity as first-party errors and whether you show UI for them.

Retry.
A boundary fallback with a Retry button should remount a clean subtree or otherwise clear the failed state. A toast “Retry” needs a clear action that actually re-runs the operation.

A common misunderstandings

  • “Error boundaries catch all errors.”
    They catch a specific class of render-time failures in their subtree. Async and event-handler errors need other paths.

  • “Global toasts are enough for reliability.”
    Toasts do not isolate a broken tree or recover a consistent UI state. They only notify.

  • “If we report to Sentry/Datadog we can show less in the UI.”
    Reporting helps you fix the bug later. The user still needs a coherent response now.

What this changes in an application

Users experience failures as “the app ate my work,” “the screen went blank,” or “I don’t know if that saved.” A clear separation of surfaces keeps recoverable problems local, isolates hard failures, and still gives you the telemetry to fix what is broken. Teams that collapse everything into one mechanism usually end up either alarming users too much or failing silently.

Questions worth exploring next

  • What kinds of errors do error boundaries not catch?
  • How do you avoid double-reporting the same error to your observability tool?
  • When would you choose an inline error over a toast over a full-section fallback?
  • How should optimistic UI failures interact with your error surfaces?

References and next steps

  • Framework docs on error boundaries / error handling (React, Vue, Svelte, etc.) — the exact APIs differ; the layering does not.
  • Your observability vendor’s guidance on client-side error reporting — sampling, fingerprinting, and PII.
  • web.dev — Error handling — practical articles on resilient UI patterns (search for current guidance on async errors and UX).

Explore next