UI Error Boundary

UI Error Boundary

The UI Error Boundary is the final safety net for errors that escape execution and rendering logic in the client application.

It exists to protect the user experience, not to perform recovery, orchestration, or domain handling.

Purpose

The UI Error Boundary exists to solve one problem:

Ensure that unhandled errors do not crash the application silently or expose internal system details.

It provides:

• a stable fallback UI
• clear recovery actions
• a safe external error surface

What the UI Error Boundary Is

• A presentation-layer safeguard
• A user-facing failure surface
• A recovery affordance (refresh / navigate back)

What the UI Error Boundary Is Not

The UI Error Boundary is not:

• a business logic handler
• a retry mechanism
• a domain decision point
• a place to branch on error codes
• a substitute for execution boundaries

It does not "handle" errors — it contains and presents them.

Execution Context

• The UI Error Boundary runs only in the client
• It is invoked by the framework when:
  • rendering fails
  • data fetching throws during render
  • an error escapes component execution

It does not intercept:

• background jobs
• API execution
• server-side logic

Error Shape Expectations

The UI Error Boundary may receive:

• a normalized AppError
• a framework error
• an unexpected runtime error

The boundary must not assume error shape.
It should rely only on:

• error.message (safe to display)
• framework-provided metadata (e.g. digest)

Presentation Rules

The UI Error Boundary must:

• show a generic, calm failure message
• avoid exposing internal error codes
• avoid stack traces or raw objects
• offer clear recovery actions

Typical actions include:

• refresh the current route
• navigate back
• contact support

Relationship to Error Handling Layers

AsyncHandler

• Normalizes errors during execution
• Operates before rendering
• UI Error Boundary does not replace it

AppError & ErrorMap

• Define error shape and semantics
• UI boundary does not inspect or branch on codes
• Messages are assumed externally safe

Transport Error Adapters

• Convert AppError to protocol responses
• UI boundary is not transport-aware

Design Principles

Containment Over Recovery

The UI boundary contains failure.
Recovery logic belongs in:

• feature-specific UI
• explicit user actions
• service retries (if any)

Safety Over Specificity

When in doubt:

• show less information
• keep messaging generic
• prioritize user trust

Deterministic UX

Errors should result in:

• predictable UI
• consistent actions
• no partial renders or broken states

Summary

The UI Error Boundary is the last line of defense.

It ensures that:

• failures are visible
• users are not stranded
• internal systems remain opaque

It does not fix errors — it keeps failure boring, safe, and recoverable.