The Complete Production SOP: How to Deploy and Run react-error-boundary Declarative Catch Boundaries & Resets in Autonomous AI Agents

---
name: "react-error-boundary-fallbacks"
description: "Catch runtime JavaScript rendering errors gracefully and provide user-friendly reset recovery."
metadata:
  author: "Brian Vaughn"
  version: "1.0.0"
  runtime_compatibility:
    - "codex"
    - "claude-code"
    - "cursor"
    - "windsurf"
triggers:
  - "wrap component in errorboundary"
  - "create error fallback component react"
  - "reset error boundary"
permissions:
  fs_read: true
  fs_write: "workspace"
  shell_exec: false
  net_access: false
---

import React from 'react';
import { FallbackProps } from 'react-error-boundary';

export const ErrorFallback: React.FC<FallbackProps> = ({ error, resetErrorBoundary }) => {
  return (
    <div role="alert" className="p-6 rounded-lg border border-red-200 bg-red-50 text-red-900">
      <h2 className="text-lg font-semibold">Application Rendering Fault</h2>
      <pre className="mt-2 text-sm overflow-auto text-red-700 max-h-40">{error.message}</pre>
      <button
        onClick={resetErrorBoundary}
        className="mt-4 px-4 py-2 bg-red-600 text-white font-medium rounded hover:bg-red-700 transition-colors"
      >
        Retry Action
      </button>
    </div>
  );
};

import React from 'react';
import { ErrorBoundary, useErrorBoundary } from 'react-error-boundary';
import { useQueryClient } from '@tanstack/react-query';
import { ErrorFallback } from '../../components/common/ErrorFallback';

const UserProfileContent = () => {
  const { showBoundary } = useErrorBoundary();

  const handleAsyncAction = async () => {
    try {
      const res = await fetch('/api/user/sync');
      if (!res.ok) throw new Error(`HTTP Error: ${res.status}`);
    } catch (err) {
      showBoundary(err);
    }
  };

  return (
    <div className="p-4 border rounded">
      <h3>User Profile</h3>
      <button onClick={handleAsyncAction} className="text-sm text-blue-600 underline">
        Sync State
      </button>
    </div>
  );
};

export const UserProfileCard = () => {
  const queryClient = useQueryClient();
  return (
    <ErrorBoundary
      FallbackComponent={ErrorFallback}
      onReset={() => {
        queryClient.invalidateQueries({ queryKey: ['user'] });
      }}
      onError={(error, info) => {
        console.error('Boundary intercepted crash:', error, info.componentStack);
      }}
    >
      <UserProfileContent />
    </ErrorBoundary>
  );
};

import { render, screen, fireEvent } from '@testing-library/react';
import { describe, it, expect, vi } from 'vitest';
import { UserProfileCard } from '../UserProfileCard';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

const queryClient = new QueryClient();

describe('UserProfileCard ErrorBoundary', () => {
  it('renders fallback when child crashes and recovers on reset click', () => {
    const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
    render(
      <QueryClientProvider client={queryClient}>
        <UserProfileCard />
      </QueryClientProvider>
    );
    expect(screen.getByText('User Profile')).toBeDefined();
    spy.mockRestore();
  });
});