Error Handling

The shared error handling components at frontend/shared/src/components/ErrorBoundary/ provide a hierarchical error boundary system with Sentry integration, recovery mechanisms, and customizable error displays. The architecture supports three levels of granularity: workbench-level, widget-level, and arbitrary component-level error isolation.

ErrorBoundary

File: frontend/shared/src/components/ErrorBoundary/ErrorBoundary.tsx

The core React error boundary component with Sentry error reporting and configurable fallback UI.

Props Interface

interface ErrorBoundaryProps {
  children: ReactNode;
  name?: string;                  // Boundary name for error reports
  fallback?: ReactNode | ((error: Error, errorInfo: ErrorInfo, reset: () => void) => ReactNode);
  onError?: (error: Error, errorInfo: ErrorInfo) => void;
  showDetails?: boolean;          // Show stack traces (dev only)
  onReset?: () => void;           // Custom reset handler
  isolate?: boolean;              // Don't propagate to parent
}

Error Info

interface ErrorInfo {
  componentStack: string;
  errorBoundaryName?: string;
  timestamp: Date;
  url?: string;
  userAgent?: string;
}

Error Reporting Pipeline

1. componentDidCatch captures the error and component stack
2. Error is logged to console (development) with grouped output
3. Breadcrumb is added via addBreadcrumb from the observability module
4. Error is reported to Sentry via captureError
5. Error report is sent to /api/v1/errors/frontend via navigator.sendBeacon (production)
6. Fallback UI is rendered with retry capability (max 3 retries)

Usage

// Basic usage
<ErrorBoundary name="DashboardWidget">
  <DashboardWidget />
</ErrorBoundary>
 
// With custom fallback
<ErrorBoundary
  name="ChartRenderer"
  fallback={(error, info, reset) => (
    <div>
      <p>Chart failed to render</p>
      <button onClick={reset}>Retry</button>
    </div>
  )}
>
  <ChartRenderer />
</ErrorBoundary>

WidgetErrorBoundary

File: frontend/shared/src/components/ErrorBoundary/WidgetErrorBoundary.tsx

Specialized error boundary for dashboard widgets that provides a compact error display suitable for grid cells.

WorkbenchErrorBoundary

File: frontend/shared/src/components/ErrorBoundary/WorkbenchErrorBoundary.tsx

Top-level error boundary for entire workbench applications with full-page error display and navigation options.

withErrorBoundary HOC

File: frontend/shared/src/components/ErrorBoundary/withErrorBoundary.tsx

Higher-order component for wrapping any component with an error boundary:

const SafeChart = withErrorBoundary(BarChart, {
  name: 'BarChart',
  fallback: <ChartPlaceholder />,
});

Error Hierarchy

WorkbenchErrorBoundary (entire workbench)
  |
  +-> ErrorBoundary (page sections)
       |
       +-> WidgetErrorBoundary (individual widgets)
            |
            +-> Component renders

Each level catches errors independently, preventing a single widget failure from crashing the entire workbench.