Instrumentation hook for server-side errors

[lforst]

Goals

1. Structured collection of server-side errors
2. Exposing all errors to user-land
3. Filter out control-flow errors that come from React (ie. filter out errors that are not caused by bugs)

Non-Goals

1. A hook for client-side errors

Background

As of today, it is impossible to intercept and collect errors that happen within a nested server component:

// app/page.tsx

export const dynamic = "force-dynamic";

export default function Page() {
  return <ComponentThatThrows />;
}

function ComponentThatThrows() {
  throw new Error("boom");
  return null;
}

The error is logged to the console, however, it is not exposed to user-land in any way.

Proposal

Just an idea: Similar to how the register hook in instrumentation.ts works, we could have an onError hook in instrumentation.ts that receives all errors that happen and is provided with additional information.

Prior art:

• SvelteKit: https://kit.svelte.dev/docs/hooks#shared-hooks-handleerror
• Nuxt: https://nuxt.com/docs/getting-started/error-handling

[lforst]

Update: Seems like the team is working on it <3 #67539

[tyteen4a03]

@lforst I am on the latest canary, does this mean this will work without further setup?

[lforst]

You'll need to add the hook in your instrumentation.ts as outlined in this PR description: getsentry/sentry-javascript#12885 (comment)

[giovannibenussi]

Any ideas where this is going to reach a stable release? I don't want to switch to canary and just want to have an idea of how much we need to wait for this :)

BTW, and just to be sure, we are not getting errors on Sentry when using server actions and I'm assuming that it's related with this issue too. Do you know if that's the case?

[lforst]

@giovannibenussi I think this will hit stable at the same time when next@15 lands which is dependent on react@19 but I'll let the Vercel folks confirm that :)

As far as server actions go, as of now (assuming you're not using the new hook yet) you need to manually wrap server actions in Sentry.withServerActionInstrumentation().

[giovannibenussi]

Hey, right, we're not using the hook because we don't want to switch to canary.
I didn't know about the Sentry.withServerActionInstrumentation function. I tested it and works as expected, thanks for suggesting that, we'll be using it until the hook reaches a stable release!

[allyjarjour]

hi @lforst , really excited about this upcoming feature! Our process for handling server errors and capturing for Sentry feels very convoluted at the moment. Just want to make sure I understand implementation details, would the hook in instrumentation.ts capture all errors (client and server) and automatically report to Sentry? And if so, would this replace the call to Sentry.captureException in the error boundaries useEffect? I tried testing it out w/ latest Nextjs and Sentry canary versions but didn't have success, likely due to some breaking changes that would need to be addressed first on our end. We're currently on Next 14.1.1.

[lforst]

No this wouldn't replace the captureException calls in the error.ts files. This hook only applies to the server side and error.ts is entirely client side.

[allyjarjour]

cool, that sounds good. we currently re-throw a custom error in our fetch helper in order to capture server errors so would be great to remove that logic ! excited for the release of this 🥳

[huozhi]

📣 Hi here, to share some updates, we introduced a new API called onRequestError for instrumentation.js on latest canary release of Next.js to help capture the server-side errors. 🚀 Check the docs for more details and API reference.

We'd love to hear your feedback on it, lmk if there's anything else we can help to make your error tracking life easier! 🙏