---
title: "UI Error Boundary"
slug: "ui-error-boundary"
updated: 2026-08-26T07:39:52Z
published: 2026-08-26T07:39:52Z
canonical: "docs.viewlift.com/ui-error-boundary"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.viewlift.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.