Next.js

Epure error tracking takes errors from a Next.js app through Sentry's own SDK, @sentry/nextjs. Install it, set dsn to your Epure project's DSN in instrumentation-client.ts, sentry.server.config.ts and sentry.edge.config.ts, and set tracesSampleRate: 0. There is no Epure package to install. Epure's ingest tests parse Next.js envelopes from @sentry/nextjs 7.120.0 through 11.10.0. Epure stores errors only, so keep Sentry if you need tracing, session replay or profiling.

Last checked on 6 Nov 2026 against Epure v0.2.0 and Sentry's Next.js manual setup and build options. This page covers one Next.js app with browser, server and edge code. A Vite or CRA single-page app uses Browser, and a standalone Express API uses Node.js. To move an existing Sentry project, start with move from Sentry to Epure without changing your SDK.

File names follow Sentry's manual setup for @sentry/nextjs 10 and 11 with the App Router, checked 6 Nov 2026. Put the files in src/ if your app uses src/app.

How do I set up @sentry/nextjs to send errors to Epure?

Setting up @sentry/nextjs for Epure takes four steps: install the package, set two DSN variables, create the six files in the table, then throw one test error. A coding agent can run each step from this page alone, except copying the DSN, which a person reads from the Epure project settings. Epure accepts the SDK's envelopes at /api/PROJECT_ID/envelope/ and answers 202 once the event is committed to Postgres.

npm install @sentry/nextjs

1. Set SENTRY_DSN and NEXT_PUBLIC_SENTRY_DSN to the same Epure DSN.
2. Create the init files and instrumentation.ts (code below).
3. Wrap next.config.ts with withSentryConfig.
4. Throw a test error from the browser and from a route handler, then open Issues in Epure.

Which environment variables does Next.js need: SENTRY_DSN or NEXT_PUBLIC_SENTRY_DSN?

Next.js needs both DSN variables: SENTRY_DSN for server and edge code, and NEXT_PUBLIC_SENTRY_DSN for the browser, because Next.js only inlines variables prefixed with NEXT_PUBLIC_ into client bundles. Set both to the same Epure DSN. Without NEXT_PUBLIC_SENTRY_DSN, browser errors, hydration errors included, never leave the tab. The DSN ends up in the client bundle; Sentry's own snippets work the same way.

# .env.local, and the same values in your host's environment settings
SENTRY_DSN=https://PUBLIC_KEY@app.epure.sh/PROJECT_ID
NEXT_PUBLIC_SENTRY_DSN=https://PUBLIC_KEY@app.epure.sh/PROJECT_ID
# Optional: one release string for errors and source maps
NEXT_PUBLIC_APP_RELEASE=my-app@1.0.0

Copy the exact DSN from your Epure project settings. The last path segment is the numeric project ID. A self-hosted instance uses its own host, for example https://PUBLIC_KEY@errors.example.com/PROJECT_ID. NEXT_PUBLIC_APP_RELEASE is a name this page uses; any variable works if all three init files and your source-map upload read the same value.

What goes in instrumentation-client.ts, sentry.server.config.ts and sentry.edge.config.ts?

Each of the three @sentry/nextjs init files calls Sentry.init with the Epure DSN, a release and tracesSampleRate: 0. The client file runs in the browser, the server file in the Node.js runtime, and the edge file in middleware and edge routes. Leave out replayIntegration() and the replay sample rates. Epure drops transactions, replays and profiles at ingest, so sending them only costs your users bandwidth.

// instrumentation-client.ts
import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  release: process.env.NEXT_PUBLIC_APP_RELEASE,
  environment: process.env.NODE_ENV,
  tracesSampleRate: 0,
});

With @sentry/nextjs 7.x, the client file is sentry.client.config.ts at the app root and the SDK loads the server and edge configs itself, without instrumentation.ts. The dsn and sample-rate lines are the same.

Ran Sentry's wizard (npx @sentry/wizard@latest -i nextjs)? Change one line: the DSN

Sentry's wizard, npx @sentry/wizard@latest -i nextjs, writes the same files this page describes, so a project that already ran it needs one change for Epure: the DSN. Sentry's snippets put the DSN as a string in instrumentation-client.ts, sentry.server.config.ts and sentry.edge.config.ts, so that one line appears three times. Replace each copy with your Epure DSN, or with the environment variables above. Every other edit below is optional and only stops the SDK sending data that Epure drops.

 Sentry.init({
-  dsn: "https://PUBLIC_KEY@o123456.ingest.sentry.io/PROJECT_ID",
+  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN, // SENTRY_DSN in the server and edge files
-  tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,
+  tracesSampleRate: 0,
-  integrations: [Sentry.replayIntegration()],
-  replaysSessionSampleRate: 0.1,
-  replaysOnErrorSampleRate: 1.0,
 });

Then check what else the wizard added:

• withSentryConfig in next.config.ts: with org, project and authToken still set, next build keeps uploading source maps to sentry.io. Remove them and the .env.sentry-build-plugin file (it holds a Sentry auth token) once you stop using Sentry, and upload maps to Epure as described in source maps.
• tunnelRoute: remove it while you test with Epure. We have not tested Sentry's tunnel route against a DSN outside sentry.io.
• The example page at /sentry-example-page: keep it for the verify step. Its "Throw Sample Error" button now reports to Epure.
• onRouterTransitionStart in the client file only feeds navigation tracing. Leaving it in place is harmless with tracesSampleRate: 0.

Which @sentry/nextjs versions work with Epure?

Epure's ingest test suite parses six Next.js envelopes from @sentry/nextjs 7.120.0, 8.30.0, 9.1.0, 10.76.2 and 11.10.0, each sent raw and gzip-compressed (crates/server/tests/ingest_envelope.rs). They are part of the 102 envelopes from 22 Sentry SDK fixture families listed in the Sentry SDK compatibility matrix. Sentry's current setup needs Next.js 14 or later, and onRequestError needs Next.js 15 with @sentry/nextjs 8.28.0 or later. Versions after 11.10.0 are untested, so send the test error below before you rely on one.

What does Epure capture from a Next.js app?

Epure captures every exception that reaches a @sentry/nextjs handler. Browser errors and hydration mismatches arrive through instrumentation-client.ts, render errors through app/global-error.tsx, and Server Component, route handler, Server Action and middleware errors through onRequestError. Each one is grouped into an issue by fingerprint, with its breadcrumbs. Transactions, replays and profiles are dropped at ingest, and log items are not stored.

A loop of one error stays one issue. Epure keeps up to 100 events per minute for an identical error and counts the rest, so the other issues in the inbox stay readable (how flood isolation works).

How do I capture a handled error in Next.js?

A handled error in Next.js reaches Epure only when you report it, because onRequestError and the browser handlers see uncaught exceptions only. Call Sentry.captureException in the catch block, in a Server Action, route handler or client component alike. The event carries the same release and environment as uncaught errors, and Epure groups it with them under one fingerprint.

import * as Sentry from "@sentry/nextjs";

try {
  await chargeCustomer(invoiceId);
} catch (error) {
  Sentry.captureException(error);
  throw error;
}

How do I get readable Next.js stack traces?

Production Next.js client bundles are minified, so a browser frame reads like page-3f2a1c.js:1:4821 until Epure has the matching .map file for the event's release. Epure demangles JavaScript and TypeScript frames when the event carries a release and a map for that file was uploaded under the same release string. Server frames often arrive readable already: Sentry's Next.js source maps guide notes that server source maps are kept for runtime error reporting.

Sentry's build plugin uploads maps to Sentry during next build. With Epure, the upload is a separate step after the build, done with curl from CI, because Sentry's uploader does not produce readable frames in Epure v0.2.0. The script, the naming rule and the 2 MB upload limit are in upload JavaScript source maps to Epure.

How do I verify the Next.js setup?

Verifying the Next.js setup takes two thrown errors, one from the browser and one from the server, then a look at Issues in Epure. Run a production build (next build && next start) or deploy to staging, because development mode can show the Next.js error overlay first. In the browser Network tab, the request to /api/PROJECT_ID/envelope/ should return 202. Errors typed into the devtools console are not captured, as Sentry's own guide notes.

// app/epure-test/page.tsx
"use client";

export default function EpureTest() {
  return (
    <button
      onClick={() => {
        throw new Error("Epure test: client");
      }}
    >
      Throw a client error
    </button>
  );
}

Open /epure-test, click the button, then open /api/epure-test. Two issues, Epure test: client and Epure test: server, should appear in Epure's Issues view. If you connected the Epure MCP server, ask your agent to explain the latest Epure issue (connect Epure to Claude Code, Cursor or Codex). Delete both test routes afterwards.

How do I roll back from Epure to Sentry in Next.js?

Rolling back is one change: restore the previous DSN in SENTRY_DSN and NEXT_PUBLIC_SENTRY_DSN (or in the three init files) and redeploy. Nothing in this setup is specific to Epure, so the same files keep working with Sentry. Issues already in Epure stay readable for your plan's retention, 30 days on Pro. To stop sending everywhere, leave both DSN variables empty: Sentry's SDKs send nothing without a dsn.

Keep the DSN empty in CI and end-to-end tests too. A placeholder string still starts the SDK, a trap one r/nextjs thread sums up as "placeholder tokens still initialize Sentry/PostHog in E2E" (r/nextjs).

401 invalid_dsn

Epure returns 401 invalid_dsn when a request carries no valid sentry_key. In a Next.js app the usual cause is a DSN copied with a typo, a DSN from another Epure instance, or a Sentry DSN still hard-coded in one of the three init files after the wizard. Search the project for ingest.sentry.io, recopy the DSN from your Epure project settings, and rebuild, because NEXT_PUBLIC_SENTRY_DSN is inlined at build time. A revoked key returns 403 dsn_revoked instead.

403 subscription_inactive

Epure Cloud returns 403 subscription_inactive when the workspace has no paid plan, no past-due plan and no running trial, for example after the 14-day trial ends without a plan. Ingest stops and existing issues stay readable. Choose a plan on Epure pricing and the same DSN is accepted again. Self-hosted Epure never returns this code. The full list of ingest codes is in API errors.

blocked by CORS policy in the browser console

A browser blocked by CORS policy message on /api/PROJECT_ID/envelope/ means the Epure instance does not allow your site's origin. On a self-hosted instance, add the exact origin, such as https://app.example.com, to EPURE_CORS_ORIGINS and restart Epure (self-hosting troubleshooting). Server and edge errors are not affected, because they never pass through the browser. Ingest answers are not CORS-readable for origins outside the allowlist.

Event accepted with 202 but no issue in Epure

A 202 from Epure means the event was committed, so a missing issue is almost always a filter or a project mix-up. Check the environment filter in Issues against the environment you set (production or development), and check that the DSN's numeric project ID is the project you are looking at. A repeat of an existing error adds to that issue's count instead of creating a new row. The full checklist is in event sent but no issue in Epure.

Next

• Upload JavaScript source maps to Epure
• Verify the first event
• Sentry SDK compatibility matrix
• JavaScript and TypeScript options