How to Trigger React Error Boundary (Dev and Test)

4 min read.
Tags: reactjavascriptjest

To trigger a React error boundary, throw an error while a child component is rendering. That is the path React error boundaries are built to catch.

If the error happens in an event handler or async callback, the boundary will not catch it on its own. In that case, catch the error and pass it to showBoundary from react-error-boundary.

Quick answer

For a quick development check, add a temporary render-time crash:

function Profile({ shouldCrash }: { shouldCrash: boolean }) {
  if (shouldCrash) {
    throw new Error('Intentional crash for testing boundary');
  }

  return <div>Profile loaded</div>;
}

Then render it inside an error boundary:

import { ErrorBoundary } from 'react-error-boundary';

<ErrorBoundary fallback={<p>Something went wrong.</p>}>
  <Profile shouldCrash />
</ErrorBoundary>;

If the fallback appears, the boundary is wired correctly.

What a React error boundary catches

A React error boundary catches errors that happen below it during:

  • rendering
  • lifecycle methods
  • constructors of child components

It does not catch errors from:

  • event handlers
  • async callbacks such as setTimeout
  • server-side rendering
  • errors thrown inside the error boundary itself

That last distinction matters. If you click a button and throw inside onClick, React will not swap in the fallback UI. The error happened after rendering, outside the path that error boundaries handle by default.

Basic render-time example

Use a small component that crashes only when you ask it to. I prefer a prop or local debug flag because it is easy to remove after testing.

function CrashToggle({ enabled }: { enabled: boolean }) {
  if (enabled) {
    throw new Error('CrashToggle crashed on purpose');
  }

  return <p>No crash.</p>;
}

export function SettingsPage() {
  const shouldCrash = false; // Flip to true while testing, then remove it.

  return (
    <ErrorBoundary fallback={<p>Settings failed to render.</p>}>
      <CrashToggle enabled={shouldCrash} />
    </ErrorBoundary>
  );
}

Do not leave this flag in real code. It is just a quick way to confirm that the fallback renders where you expect it to render.

Reliable Jest test pattern

In a test, the cleanest pattern is the same: render a child component that throws during render, then assert the fallback.

import { render, screen } from '@testing-library/react';
import { ErrorBoundary } from 'react-error-boundary';

function CrashOnRender() {
  throw new Error('boom');
}

test('renders fallback when a child crashes', () => {
  const consoleError = jest
    .spyOn(console, 'error')
    .mockImplementation(() => {});

  try {
    render(
      <ErrorBoundary fallback={<p data-testid="fallback">Fallback</p>}>
        <CrashOnRender />
      </ErrorBoundary>,
    );

    expect(screen.getByTestId('fallback')).toBeInTheDocument();
  } finally {
    consoleError.mockRestore();
  }
});

React logs render errors to the console during tests. Mocking console.error keeps the test output readable without changing the behavior being tested. If you use Vitest, use vi.spyOn instead of jest.spyOn.

Trigger an error boundary from an event handler

Errors in onClick, onSubmit, timers, and promise callbacks do not automatically reach an error boundary. With react-error-boundary, forward the error yourself:

import { useErrorBoundary } from 'react-error-boundary';

function SaveButton() {
  const { showBoundary } = useErrorBoundary();

  async function handleClick() {
    try {
      await saveData();
    } catch (error) {
      showBoundary(error);
    }
  }

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

Now the failed event path can still render the boundary fallback. This is useful for async UI actions where you want the whole section to fail closed instead of showing a small inline error.

Verify the boundary is working

Check these three things:

  • The fallback renders when a child throws during render.
  • The fallback does not render when the crash component is disabled.
  • Event or async errors call showBoundary(error) if you expect the boundary to handle them.

For manual testing, make the crash temporary and obvious. For automated testing, keep the crash component inside the test file so it cannot leak into production code.

Common mistakes

The most common mistake is throwing inside a click handler and expecting the boundary to catch it. Use showBoundary for that path.

Another mistake is placing the boundary below the component that crashes. Error boundaries catch errors in their children, not in parents or sibling components.

Also check that the fallback itself does not throw. A broken fallback can make it look like the original boundary failed, when the second error is the real problem.

Conclusion

To trigger a React error boundary, throw during render in a child component. Use that pattern for quick browser checks and Jest tests. For event handlers or async code, catch the error and send it to the boundary with showBoundary.

Related Posts