Skip to content

Frontend Error Boundaries and Fallback Strategies: Building Resilient Applications

Frontend application stability cannot be guaranteed solely by "not writing bugs." As application complexity grows—dynamic loading, async interactions, third-party dependencies, diverse user environments—runtime errors are inevitable. The goal of a resilient architecture is not to eliminate all errors, but to ensure that when errors occur, users can still complete their tasks, or at least experience graceful degradation rather than a white screen.

Frontend Error Classification ​

Effective error handling starts with proper classification. Frontend runtime errors can be categorized into four types:

JS Runtime Errors: Type errors, null references, range errors, etc. These errors are thrown synchronously and can be caught by try-catch and Error Boundaries.

Async Errors: Errors thrown in setTimeout, setInterval, and event callbacks. They don't bubble up to outer try-catch blocks and require the global window.onerror handler.

Promise Rejections: Unhandled rejections in Promise chains. Captured via the unhandledrejection event.

Resource Loading Errors: JS/CSS/image loading failures. <script onerror> or PerformanceObserver can capture these, but they don't trigger window.onerror.

typescript
// Complete error capture system by classification
function setupGlobalErrorHandlers() {
  // 1. Synchronous runtime errors
  window.addEventListener('error', (event) => {
    reportError({
      type: 'runtime',
      message: event.message,
      filename: event.filename,
      lineno: event.lineno,
      colno: event.colno,
      stack: event.error?.stack,
    });
    // Prevent default console.error
    event.preventDefault();
  });

  // 2. Unhandled Promise rejections
  window.addEventListener('unhandledrejection', (event) => {
    reportError({
      type: 'promise_rejection',
      reason: event.reason?.message || String(event.reason),
      stack: event.reason?.stack,
    });
    event.preventDefault();
  });

  // 3. Resource loading errors (capture phase)
  window.addEventListener('error', (event) => {
    const target = event.target;
    if (target && (target.tagName === 'SCRIPT' || target.tagName === 'LINK' || target.tagName === 'IMG')) {
      reportError({
        type: 'resource_error',
        tagName: target.tagName,
        src: target.src || target.href,
      });
    }
  }, true); // Must listen in capture phase

  // 4. Cross-origin script errors ("Script error")
  // Requires <script crossorigin="anonymous"> + server-side CORS headers
}

Cross-origin script errors are a common blind spot—when loading cross-origin scripts, the browser returns only "Script error." with no stack trace for security reasons. The solution is to add crossorigin="anonymous" to the <script> tag and ensure the CDN returns the correct Access-Control-Allow-Origin header.

React Error Boundary: Principles and Limitations ​

React's Error Boundary is a component-level error capture mechanism. When a child component subtree throws an error during rendering, lifecycle, or in a constructor, the Error Boundary can catch it and display a fallback UI.

tsx
// components/ErrorBoundary.tsx
import React, { Component, type ReactNode } from 'react';

interface Props {
  children: ReactNode;
  fallback?: ReactNode | ((error: Error, reset: () => void) => ReactNode);
  onError?: (error: Error, errorInfo: React.ErrorInfo) => void;
}

interface State {
  hasError: boolean;
  error: Error | null;
}

export class ErrorBoundary extends Component<Props, State> {
  state: State = { hasError: false, error: null };

  static getDerivedStateFromError(error: Error): State {
    return { hasError: true, error };
  }

  componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
    this.props.onError?.(error, errorInfo);
  }

  reset = () => {
    this.setState({ hasError: false, error: null });
  };

  render() {
    if (this.state.hasError && this.state.error) {
      if (typeof this.props.fallback === 'function') {
        return this.props.fallback(this.state.error, this.reset);
      }
      return this.props.fallback ?? <DefaultFallback onRetry={this.reset} />;
    }
    return this.props.children;
  }
}

function DefaultFallback({ onRetry }: { onRetry: () => void }) {
  return (
    <div role="alert" className="error-fallback">
      <h3>Something went wrong in this section</h3>
      <button onClick={onRetry}>Retry</button>
    </div>
  );
}

Key limitations of Error Boundaries: They do not catch async errors, event callback errors, or Promise rejections. These errors bypass Error Boundaries:

tsx
function BuggyComponent() {
  // ❌ Not caught by Error Boundary
  useEffect(() => {
    setTimeout(() => {
      throw new Error('async error');
    }, 1000);
  }, []);

  // ❌ Not caught by Error Boundary
  const handleClick = async () => {
    await fetchData();
    throw new Error('event handler error');
  };

  // ✅ Caught by Error Boundary (thrown during render)
  const data = useSyncExternalStore(subscribe, getSnapshot);
  if (data === null) throw new Error('render error');

  return <button onClick={handleClick}>click</button>;
}

For async errors, you need try-catch inside event handlers, or use React 19's use() Hook combined with Suspense and Error Boundaries to handle async states.

Nesting strategy: There shouldn't be just one global Error Boundary. They should be nested by route and by component region—a navigation bar crash shouldn't cause a full-page white screen, and a sidebar crash shouldn't affect the main content area.

tsx
<App>
  <ErrorBoundary fallback={<NavFallback />}>
    <Navigation />
  </ErrorBoundary>
  <ErrorBoundary fallback={<RouteFallback />}>
    <Routes>
      <Route path="/dashboard" element={
        <ErrorBoundary fallback={<DashboardFallback />}>
          <Dashboard />
        </ErrorBoundary>
      } />
    </Routes>
  </ErrorBoundary>
</App>

Vue 3's Error Capture Mechanism ​

Vue 3 provides two levels of error handling: onErrorCaptured and app.config.errorHandler.

typescript
// Vue 3 Error Boundary component
import { defineComponent, ref, onErrorCaptured, h } from 'vue';

export const ErrorBoundary = defineComponent({
  name: 'ErrorBoundary',
  props: {
    fallback: { type: Function, required: true },
  },
  setup(props, { slots }) {
    const error = ref<Error | null>(null);

    onErrorCaptured((err, instance, info) => {
      error.value = err;
      // Report the error
      reportError({ type: 'vue_error', error: err, info });
      // Return false to stop the error from propagating upward
      return false;
    });

    return () => {
      if (error.value) {
        return props.fallback(error.value, () => {
          error.value = null;
        });
      }
      return slots.default?.();
    };
  },
});
typescript
// Global error handler
// main.ts
import { createApp } from 'vue';
import App from './App.vue';

const app = createApp(App);

app.config.errorHandler = (err, instance, info) => {
  reportError({
    type: 'vue_global',
    error: err instanceof Error ? err : new Error(String(err)),
    componentName: instance?.$options.name,
    info,
  });
};

// Capture Vue internal warnings (development mode)
app.config.warnHandler = (msg, instance, trace) => {
  if (import.meta.env.DEV) {
    console.warn(`[Vue warn] ${msg}\n${trace}`);
  }
};

app.mount('#app');

Vue's onErrorCaptured has broader coverage than React Error Boundaries—it can catch errors inside component event handlers and lifecycle hooks. However, rejections in async setup() still need manual handling.

Fallback Strategy Design: UI, Functional, and Data Degradation ​

Error capture is just the first step; true resilience comes from fallback strategies. Degradation operates at three levels:

UI Degradation—replace the crashed component region with a simplified alternative. For example, when a chart component crashes, fall back to a table; when a rich text editor crashes, fall back to a plain text input.

Functional Degradation—when core functionality is unavailable, provide alternative paths. For example, when real-time collaboration disconnects, degrade to local editing with a manual sync prompt.

Data Degradation—when fresh data fetch fails, use cached data and annotate it as "data may be stale."

typescript
// Combined use of fallback strategies
function useUserData(userId: string) {
  const { data, error, isLoading } = useQuery({
    queryKey: ['user', userId],
    queryFn: () => userApi.fetch(userId),
    // Data degradation: use cache on failure
    retry: 2,
    staleTime: 5 * 60 * 1000,
    cacheTime: 30 * 60 * 1000,
  });

  // Functional degradation: use local data when API is unavailable
  const fallbackData = useLocalUserData(userId);

  const effectiveData = data ?? fallbackData.value;
  const isStale = !!error && !!data;

  return {
    data: effectiveData,
    isLoading,
    isStale, // Flag indicating data may be stale
    error,
  };
}
tsx
// UI degradation: Chart → Table
function DataVisualization({ data }: { data: ChartData[] }) {
  return (
    <ErrorBoundary
      fallback={(error, reset) => (
        <div>
          <p>Chart rendering failed, switched to table view</p>
          <DataTable data={data} />
          <button onClick={reset}>Retry Chart</button>
        </div>
      )}
    >
      <ComplexChart data={data} />
    </ErrorBoundary>
  );
}

Error Reporting and Aggregation ​

After errors are captured, they need to be reported to a monitoring platform. Sentry is the most mature solution, but a self-built error monitoring system has advantages in data privacy and customization.

typescript
// Reporter abstraction
interface ErrorReporter {
  capture(error: ErrorInfo): void;
  setUser(user: { id: string; email?: string }): void;
  setContext(key: string, value: Record<string, unknown>): void;
}

// Sentry implementation
class SentryReporter implements ErrorReporter {
  constructor(dsn: string) {
    Sentry.init({
      dsn,
      tracesSampleRate: 0.1, // 10% performance sampling
      // Filter noisy errors
      beforeSend(event) {
        // Filter known harmless errors
        if (event.exception?.values?.[0]?.value?.includes('ResizeObserver')) {
          return null;
        }
        return event;
      },
    });
  }

  capture(error: ErrorInfo) {
    Sentry.captureException(error.error, {
      tags: { type: error.type },
      extra: error.context,
    });
  }

  setUser(user) { Sentry.setUser(user); }
  setContext(key, value) { Sentry.setContext(key, value); }
}

// Custom reporter implementation
class CustomReporter implements ErrorReporter {
  private endpoint = '/api/errors';
  private queue: ErrorInfo[] = [];
  private flushTimer: number | null = null;

  capture(error: ErrorInfo) {
    this.queue.push({
      ...error,
      timestamp: Date.now(),
      url: location.href,
      userAgent: navigator.userAgent,
    });
    this.scheduleFlush();
  }

  private scheduleFlush() {
    if (this.flushTimer) return;
    // Batch reporting to reduce request count
    this.flushTimer = window.setTimeout(() => {
      const batch = this.queue.splice(0);
      this.flushTimer = null;

      // Use sendBeacon to ensure delivery during page unload
      if (navigator.sendBeacon) {
        navigator.sendBeacon(
          this.endpoint,
          JSON.stringify({ errors: batch }),
        );
      } else {
        fetch(this.endpoint, {
          method: 'POST',
          body: JSON.stringify({ errors: batch }),
          keepalive: true,
        }).catch(() => {});
      }
    }, 5000);
  }

  setUser(user) { /* Store user context */ }
  setContext(key, value) { /* Store extra context */ }
}

Contextual information in error reports is critical for debugging. A useful error report should include: the user's action path (what they clicked, which page they came from), the application version, device info, and recent network request status. This context transforms an error from "something crashed somewhere" to "user on v2.3.1, after clicking the buy button on the homepage, the payment API returned 500 and caused the crash."

Release Circuit Breaker for Canary Deployments ​

Canary deployment is the last line of defense for catching production environment issues. The circuit breaker mechanism automatically halts the release process when error rates exceed thresholds:

typescript
// Canary release circuit breaker checker
interface ReleaseHealth {
  errorRate: number;
  crashRate: number;
  sampleSize: number;
}

class ReleaseCircuitBreaker {
  private thresholds = {
    errorRate: 0.05,      // Error rate > 5% triggers circuit breaker
    crashRate: 0.01,      // Crash rate > 1% triggers circuit breaker
    minSampleSize: 100,   // Need at least 100 samples for statistical significance
  };

  async checkReleaseHealth(
    version: string,
    rolloutPercentage: number,
  ): Promise<{ shouldHalt: boolean; reason?: string }> {
    const health = await this.fetchHealthMetrics(version);

    if (health.sampleSize < this.thresholds.minSampleSize) {
      return { shouldHalt: false }; // Insufficient samples, continue observing
    }

    if (health.errorRate > this.thresholds.errorRate) {
      return {
        shouldHalt: true,
        reason: `Error rate ${(health.errorRate * 100).toFixed(1)}% exceeds threshold ${this.thresholds.errorRate * 100}%`,
      };
    }

    if (health.crashRate > this.thresholds.crashRate) {
      return {
        shouldHalt: true,
        reason: `Crash rate ${(health.crashRate * 100).toFixed(1)}% exceeds threshold ${this.thresholds.crashRate * 100}%`,
      };
    }

    return { shouldHalt: false };
  }

  private async fetchHealthMetrics(version: string): Promise<ReleaseHealth> {
    // Query error metrics for this version from the monitoring platform
    const stats = await fetch(`/api/release-stats?version=${version}`).then(
      (r) => r.json(),
    );
    return {
      errorRate: stats.errors / stats.total,
      crashRate: stats.crashes / stats.total,
      sampleSize: stats.total,
    };
  }
}

Source Map Restoration of Production Error Stacks ​

Production environments typically serve minified JS, so error stacks contain only minified line/column numbers. Source Maps can map these back to source code, but Source Map files must not be exposed to the public (equivalent to leaking source code).

The standard practice is to generate Source Maps at build time but not deploy them to the CDN—instead, upload them to the error monitoring platform:

typescript
// vite.config.ts
import { defineConfig } from 'vite';

export default defineConfig({
  build: {
    sourcemap: 'hidden', // Generate source maps but don't reference them in JS
  },
});

// Upload source maps to Sentry in CI
// .github/workflows/deploy.yml
// - name: Upload source maps to Sentry
//   run: npx sentry-cli sourcemaps upload --release=$VERSION dist/
//   env:
//     SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
// - name: Delete source maps after upload
//   run: rm -rf dist/**/*.map

The hidden mode generates Source Maps but doesn't add //# sourceMappingURL= comments to the bundle output. This way, the browser won't automatically download the Source Map, but Sentry can use the uploaded files for stack restoration.

Design Principles for Resilient Architecture ​

  1. Failure is the norm—design assuming any component can fail: API timeouts, component crashes, resource loading failures. Every failure point should have a corresponding fallback plan.
  2. Minimize blast radius—isolate failure regions with fine-grained Error Boundaries. A component crash shouldn't affect other areas. Three-level nesting: route-level, region-level, component-level.
  3. Degradation over errors—users have a better experience with a degraded UI than with an error popup. Use cached data rather than blank space when possible; show simplified UI rather than error messages when possible.
  4. Observability—every error should be reported, aggregated, and categorized. Error handling without observability is equivalent to no handling.
  5. Progressive recovery—provide a "Retry" button for users to actively recover, rather than requiring a full page refresh.

Summary ​

Building resilient frontend applications is a systems engineering effort: starting from error classification to establish a complete capture system (Error Boundary + global listeners + resource errors), designing three-level fallback strategies (UI/functional/data), building error reporting and aggregation pipelines, configuring Source Maps for production stack restoration, and using release circuit breakers to safeguard deployment safety. The core philosophy is accepting that errors will inevitably occur, but through isolation, degradation, and recovery mechanisms, users can still complete their tasks even under error conditions. Resilience is not an afterthought—it's a capability that must be built into the architecture from the design phase.

MIT Licensed