Next.js boilerplate with Sentry

Capture through the helper, not the SDK

• Use captureHandled(error, { fingerprint, tags }) from src/lib/observability/sentry.ts for anything you catch. It sets the fingerprint, the level and the mechanism consistently, and returns the event id so you can show the user a reference.
• Bare Sentry.captureException(error) is for the boundaries the framework owns: global-error.tsx, error.tsx, onRequestError. Everywhere else, a bare capture is a future issue nobody can group.
• Unhandled errors need no capture at all. The SDK already reports them, and catching an error only to re-report it hides the original stack.

Fingerprints describe the cause, not the occurrence

• A fingerprint is a constant string: "stripe.webhook.signature-invalid", "search.upstream-timeout", "pdf.parse-failed".
• It must contain no ids, no URLs with path parameters, no timestamps, no user input. A variable fingerprint creates one issue per occurrence, which is the same as having no error tracking.
• Use dotted segments: subsystem, then failure. It reads well in a list and sorts sensibly.
• Keep "{{ default }}" as the first element (the helper does this) so Sentry still splits genuinely different stacks within one class.

Why this rule exists

Sentry groups by stack trace. A shared helper (a fetchJson, a retry wrapper, a database client) means dozens of unrelated failures share their top frames and arrive as one issue titled after the helper. You get a single issue with 40,000 events and no way to tell which subsystem is broken. The fingerprint hint restores the grouping that the abstraction destroyed.

Capture at the boundary, once

• Report where you handle the error, not where it is thrown and not at every level in between. A catch that captures and rethrows produces two events for one failure.
• If you catch and continue, capture. If you catch and rethrow, do not.
• Never swallow silently. An empty catch {} is invisible in production, and no amount of monitoring will find it.
• Server Actions and Route Handlers should return a useful response and capture. Show the returned event id to the user: "reference a1b2c3d4" turns an unreproducible report into a lookup.

Levels mean something

• fatal: the process or the request is dead.
• error: the user's action failed. The default.
• warning: degraded but handled: a retry succeeded, a fallback was used.
• info: do not send it to Sentry. That is a log line.

Do not reconfigure the SDK inline

Sentry.init is called in exactly three places: sentry.server.config.ts, sentry.edge.config.ts and src/instrumentation-client.ts. Never call it again from application code, and never change beforeSend, dataCollection or the sample rates from inside a request: the change is global to the process and affects every other request it serves.

Sentry receives everything you attach to an event and stores it in a system with a wider access list than your database, in a jurisdiction you did not choose, for a retention period you did not set. Treat every field as "published to a third party", because that is what it is.

Never send

• A raw request body. Not scrubbed, not truncated, not "just the fields we need". A body is arbitrary user content and the set of fields grows without anyone revisiting this decision. scrubErrorEvent in src/lib/observability/scrub.ts drops request.data outright: do not add it back.
• Email addresses, names, phone numbers, addresses, dates of birth. Including inside a message string: throw new Error(\No user for ${email}\) puts an email in the issue title, where it is indexed and searchable.
• Cookies, Authorization headers, session ids, tokens, API keys.
• Card numbers, bank details, national ids: anywhere, in any form.
• The contents of a user's document, message or upload, including model prompts and completions.

Never enable

• A looser dataCollection (or dropping DATA_COLLECTION from a config). Sentry 11's defaults attach cookies, request bodies, query strings, database values and the client IP to every event. If someone loosens it for a debugging session, put it back in the same session. (sendDefaultPii was the Sentry 10 name for this switch; 11 removed it.)
• Session Replay without masking. It records the DOM, which is a video of what your user typed. It is off in this configuration on purpose; enabling it is a decision with a privacy review attached, not a config tweak.

Send instead

• An opaque user id and nothing else: Sentry.setUser({ id }), or identifyUser(id) from src/lib/observability/sentry.ts. That is enough to answer "how many people hit this", which is the only question the user field needs to answer.
• Counts, enums, booleans, durations, status codes. { itemCount: 47 } instead of the items. { role: "admin" } instead of the user record.
• Opaque references to a row you can look up yourself: an order id is fine when order ids are not derived from personal data.
• A stable fingerprint hint describing the class of failure.

Tags are the sharpest edge

Tags are indexed and searchable. A tag containing an email turns the error tracker into a queryable directory of your users, and it is the field people reach for first because it is the most convenient. Tags must be low-cardinality: provider, plan, route_kind, outcome. If a tag can take more than a few hundred distinct values, it does not belong in a tag.

Breadcrumbs leak without anyone adding them

Breadcrumbs are collected automatically: fetch URLs, navigations, console calls. Console breadcrumbs carry whatever was logged, which on a bad day is a whole user record from a debugging console.log someone left in.

scrubBreadcrumb drops console breadcrumbs entirely and redacts URLs. Do not relax that to "make debugging easier". Add the specific breadcrumb you need with trail() instead, with primitive data values only.

If it already happened

Deleting an event does not undelete it from every copy. Assume the data is gone: rotate any leaked credential immediately, then fix the source, then use Sentry's data-scrubbing settings as a second line. Do not stop after the settings change: server-side scrubbing runs after the data has crossed the network.