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

# React — Error Tracking

> Report errors and automatically capture uncaught exceptions from your React app to the Lerix dashboard.

## Introduction

Lerix captures errors from your React app so you can debug issues
faster. After you complete the [React installation](/frameworks/react/installation),
use `useLerix().throwError()` to send custom errors to your dashboard —
uncaught errors are captured automatically, with no extra code required.

<Note>
  Make sure your app is wrapped in `LerixProvider` before reporting errors.
</Note>

## Report an error

```tsx theme={"dark"}
import { useLerix, BugSeverity } from '@lerix-dev/lerix-react';

function MyComponent() {
  const lerix = useLerix();

  const onSomethingFailed = async () => {
    try {
      await riskyOperation();
    } catch (error) {
      lerix.throwError(
        String(error),
        undefined,
        undefined,
        BugSeverity.HIGH,
        { userId: '123', action: 'payment', amount: 100 },
      );
    }
  };
}
```

### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `issue` | `string` | Yes | Error message or description |
| `stack` | `string[]` | No | Stack trace frames. If omitted, one is captured automatically from the call site — see [Automatic stack capture](#automatic-stack-capture) below |
| `type` | `BugType` | No | Bug classification (default: `RUNTIME_ERROR`) |
| `severity` | `BugSeverity` | No | Severity level (default: `MEDIUM`) |
| `metadata` | `Record<string, unknown>` | No | Additional context to attach to the report |

### `BugType` values

| Value | Description |
| - | - |
| `RUNTIME_ERROR` | An unhandled exception thrown at runtime |
| `LOGIC_BUG` | Incorrect behavior that doesn't throw |
| `UI_BUG` | A visual or layout defect |
| `NETWORK_ERROR` | A failed or malformed network request |
| `PERFORMANCE` | Slowness, jank, or excessive resource use |
| `COMPATIBILITY` | Breaks on a specific browser or device |
| `VALIDATION_ERROR` | Invalid input passed validation it shouldn't have |
| `SECURITY` | A security-relevant defect |
| `CRASH` | The app terminated unexpectedly |
| `UNKNOWN` | None of the above |

### `BugSeverity` values

| Value | Description |
| - | - |
| `CRITICAL` | Blocks core functionality or affects all users |
| `HIGH` | Serious impact, but a workaround exists |
| `MEDIUM` | Noticeable but limited impact |
| `LOW` | Minor or cosmetic |
| `UNKNOWN` | Severity not yet assessed |

## Automatic error capture

`LerixProvider` installs error capture two ways, so nothing needs wrapping in a `try`/`catch` for baseline coverage:

* `LerixErrorBoundary` catches errors thrown during rendering — React's error boundary contract only covers the render phase, not event handlers or async code.
* Global `window.onerror` and `unhandledrejection` listeners catch everything else — event handlers, timers, promise rejections.

Unlike a native mobile crash handler, a browser tab isn't about to
terminate when one of these fires, so the report is sent immediately rather
than persisted for the next launch.

```tsx theme={"dark"}
import { LerixErrorBoundary } from '@lerix-dev/lerix-react';

<LerixErrorBoundary fallback={<p>Something went wrong.</p>}>
  <App />
</LerixErrorBoundary>
```

`fallback` can be a plain element, or a function receiving the caught error: `fallback={(error) => <p>{String(error)}</p>}`.

To disable the global handlers (e.g. if your app already has its own error reporting and you only want manual `throwError` calls):

```tsx theme={"dark"}
<LerixProvider options={{ apiKey: '...', projectId: '...', enableCrashReporting: false }}>
```

`LerixErrorBoundary` still catches render errors regardless of this flag — it's a separate, explicit component you control by where you place it.

## Automatic stack capture

When you call `throwError()` without a `stack` argument, one is captured
automatically from the call site — you only need to pass one explicitly
when reporting a caught `Error`'s own stack instead (e.g.
`error.stack?.split('\n')`).

Either way, every stack frame is resolved from its compiled/bundled
position (e.g. a bundler's output file and line) back to the original
source file and line, using the build's own source map — the same
mechanism browser DevTools use to show you readable stack traces instead
of minified bundle positions. This happens automatically; there's nothing
to configure.

<Note>
  Resolution requires a source map to be reachable at the frame's URL —
  always true in development, and true in production only if your build
  serves its `.map` files publicly. If your production build keeps source
  maps private (a common choice), frames fall back to their compiled
  position rather than failing to report — resolution is best-effort and
  never blocks or delays the report itself.
</Note>

<Tip>
  To get readable production stack traces while keeping your source maps
  private, upload them to Lerix after each build. See
  [React source maps](/frameworks/react/source-maps).
</Tip>

### Verify the integration

```tsx theme={"dark"}
lerix.throwError('Test error');
```

Then open your [dashboard](https://app.lerix.dev) — the error should appear within seconds, with a resolved stack trace pointing at this exact line.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.