React — Error Tracking

Introduction

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

Make sure your app is wrapped in LerixProvider before reporting errors.

Report an error

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 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.

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):

<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.

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.

To get readable production stack traces while keeping your source maps private, upload them to Lerix after each build. See React source maps.

Verify the integration

lerix.throwError('Test error');

Then open your dashboard — the error should appear within seconds, with a resolved stack trace pointing at this exact line.

Getting started

Frameworks

Modules

Developers

React — Error Tracking

Introduction

Report an error

Parameters

`BugType` values

`BugSeverity` values

Automatic error capture

Automatic stack capture

Verify the integration

​Introduction

​Report an error

​Parameters

​BugType values

​BugSeverity values

​Automatic error capture

​Automatic stack capture

​Verify the integration

Introduction

Report an error

Parameters

`BugType` values

`BugSeverity` values

Automatic error capture

Automatic stack capture

Verify the integration