Skip to main content

Introduction

Lerix captures errors from your Next.js app so you can debug issues faster. After you complete the Next.js 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 LerixNextProvider before reporting errors.

Report an error

Parameters

BugType values

BugSeverity values

Automatic error capture

LerixNextProvider 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.
To disable the global listeners (LerixErrorBoundary still catches render errors regardless):

Next.js’s own error boundaries

LerixErrorBoundary only catches errors below where you place it. For errors above that point — most notably in the root layout itself — Next.js requires its own file-based error boundaries (error.tsx, global-error.tsx). Call reportCaughtError directly inside those instead:
app/error.tsx

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 back to the original source file and line, using the build’s own source map — including Turbopack’s sectioned source map format. 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.
To get readable production stack traces while keeping your source maps private, upload them to Lerix after each build. See Next.js source maps.

Verify the integration

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

Filtering errors

Requires @lerix-dev/lerix-nextjs 1.3.0 or later. Two optional LerixNextProvider options decide which errors are sent. They apply to every report: LerixErrorBoundary, reportCaughtError in error.tsx, and the global handlers. Functions and RegExps can’t be passed as props from a Server Component, so set these options in a small client component of your own. apiKey and projectId still come from your NEXT_PUBLIC_ environment variables:
app/lerix.tsx
Then use it in layout.tsx in place of LerixNextProvider:
app/layout.tsx
  • ignoreErrors runs first. A string drops any error whose message contains it, ignoring case. A RegExp drops any error whose message it matches. Empty strings are skipped.
  • beforeSend then sees only what’s left. Return the event (changed or not) to send it, or null to drop it. If it throws, the original event is sent and the exception never reaches your app.
  • The message you match against is the issue title, which includes the error class, for example TypeError: boom.
beforeSend receives a LerixErrorEvent: { message, stack, type, severity, metadata? }. stack is an array of frames, already resolved through your source maps. Lerix also groups repeated errors into one issue and filters common noise on the server, for every SDK version. See How errors are grouped into issues.