fix(nextjs): Don't report Next.js prerender control flow errors

dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/api/hanging-fetch-data/route.ts

@@ -0,0 +1,3 @@
+export async function GET() {
+ return Response.json({ value: 'hanging-fetch-data' });
+}

dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/error-sentinel/[token]/loading.tsx

@@ -0,0 +1,3 @@
+export default function Loading() {
+ return <div id="sentinel-loading">Loading...</div>;
+}

dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/error-sentinel/[token]/page.tsx

@@ -0,0 +1,12 @@
+import * as Sentry from '@sentry/nextjs';
+
+// Captures an error tagged with a caller-supplied unique token. Tests use this as a drain marker: the
+// token guarantees a cache miss, so the capture always happens on request, and its arrival proves the
+// event pipeline has drained past every earlier request.
+export default async function Page({ params }: { params: Promise<{ token: string }> }) {
+ const { token } = await params;
+
+ Sentry.captureException(new Error(`error-sentinel-${token}`));
+
+ return <p id="sentinel">{token}</p>;
+}

dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/hanging-fetch/loading.tsx

@@ -0,0 +1,3 @@
+export default function Loading() {
+ return <div id="loading">Loading...</div>;
+}

dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/hanging-fetch/page.tsx

@@ -0,0 +1,10 @@
+// This `fetch()` deliberately has no cache configuration. Under Cache Components, Next.js does not
+// issue such a request during a prerender - it hands out a promise that never settles and rejects it
+// with a `HANGING_PROMISE_REJECTION` digest once the prerender is aborted. That rejection surfaces in
+// this component and therefore in the Sentry server component wrapper, which must not report it.
+export default async function Page() {
+ const response = await fetch('http://localhost:3030/api/hanging-fetch-data');
+ const data = (await response.json()) as { value: string };
+
+ return <p id="fetched-value">{data.value}</p>;
+}

dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/package.json

@@ -46,6 +46,12 @@
  "extends": "../../package.json"
  },
  "sentryTest": {
- "//": "TODO: Add variants for webpack once supported"
+ "variants": [
+ {
+ "build-command": "pnpm test:build-webpack",
+ "label": "nextjs-16-cacheComponents (webpack)",
+ "assert-command": "pnpm test:assert-webpack"
+ }
+ ]
  }
 }

dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/tests/hangingPromiseRejection.spec.ts

@@ -0,0 +1,57 @@
+import { expect, test } from '@playwright/test';
+import { waitForError, waitForTransaction } from '@sentry-internal/test-utils';
+
+const HANGING_PROMISE_DIGEST_MESSAGE = 'rejects when the prerender is complete';
+
+// Under Cache Components, Next.js aborts prerenders by rejecting the promises it handed out for
+// uncached `fetch()` calls. React discards those rejections - they never affect the response - so the
+// Sentry wrappers must not report them. See https://github.com/getsentry/sentry-javascript/issues/23592
+//
+// Note this only exercises the regression under the webpack variant: server components are wrapped by
+// `wrappingLoader`, which Turbopack builds do not run, so there is no wrapper to observe the rejection
+// there. Under Turbopack the test still asserts the route renders and reports no errors.
+test('does not capture hanging prerender promise rejections on a runtime prefetch', async ({ page, request }) => {
+ const capturedHangingPromiseErrors: string[] = [];
+ void waitForError('nextjs-16-cacheComponents', errorEvent => {
+ const value = errorEvent.exception?.values?.[0]?.value ?? '';
+ if (value.includes(HANGING_PROMISE_DIGEST_MESSAGE)) {
+ capturedHangingPromiseErrors.push(value);
+ }
+ return false;
+ });
+
+ // `Next-Router-Prefetch: 2` is what the Next.js router sends for a runtime prefetch. It makes Next.js
+ // run a prerender at request time, which is what produces the hanging promise rejection. A plain
+ // document request only replays the shell that was prerendered at build time and would not trigger it.
+ const prefetchResponse = await request.get('/hanging-fetch', {
+ headers: { RSC: '1', 'Next-Router-Prefetch': '2' },
+ });
+ expect(prefetchResponse.ok()).toBe(true);
+
+ const serverTransactionPromise = waitForTransaction('nextjs-16-cacheComponents', transactionEvent => {
+ return (
+ transactionEvent.contexts?.trace?.op === 'http.server' && transactionEvent.transaction === 'GET /hanging-fetch'
+ );
+ });
+
+ await page.goto('/hanging-fetch');
+ await expect(page.locator('#fetched-value')).toHaveText('hanging-fetch-data');
+
+ expect(await serverTransactionPromise).toBeDefined();
+
+ // Drain marker instead of a sleep: request a route that deliberately captures an error, tagged with a
+ // token unique to this run so it can never be served from cache. It is requested strictly after the
+ // prefetch, and the SDK flushes per request, so once this error arrives any error the prefetch had
+ // captured must already have arrived too. That makes the assertion below "nothing was captured"
+ // rather than "nothing had been captured yet". It doubles as a check that errors do flow at all.
+ const token = `${Date.now()}`;
+ const sentinelPromise = waitForError('nextjs-16-cacheComponents', errorEvent => {
+ return errorEvent.exception?.values?.[0]?.value === `error-sentinel-${token}`;
+ });
+
+ await page.goto(`/error-sentinel/${token}`);
+ await expect(page.locator('#sentinel')).toHaveText(token);
+ await sentinelPromise;
+
+ expect(capturedHangingPromiseErrors).toEqual([]);
+});

packages/nextjs/src/common/captureRequestError.ts

@@ -1,5 +1,6 @@
 import type { RequestEventData } from '@sentry/core';
 import { captureException, headersToDict, withScope } from '@sentry/core';
+import { isPrerenderControlFlowError } from './nextNavigationErrorUtils';
 import { flushSafelyWithTimeout, waitUntil } from './utils/responseEnd';
 
 type RequestInfo = {
@@ -18,6 +19,10 @@ type ErrorContext = {
  * Reports errors passed to the the Next.js `onRequestError` instrumentation hook.
  */
 export function captureRequestError(error: unknown, request: RequestInfo, errorContext: ErrorContext): void {
+ if (isPrerenderControlFlowError(error)) {
+ return;
+ }
+
  withScope(scope => {
  scope.setSDKProcessingMetadata({
  normalizedRequest: {

packages/nextjs/src/common/nextNavigationErrorUtils.ts

@@ -1,26 +1,62 @@
 import { isError } from '@sentry/core';
 
+// Next.js nests the "real" reason in `cause` when an error crosses certain boundaries, and
+// `unstable_rethrow` walks that chain. The cap guards against self-referencing causes.
+const MAX_CAUSE_DEPTH = 5;
+
+function hasDigest(subject: unknown, predicate: (digest: string) => boolean, depth = 0): boolean {
+ if (!isError(subject)) {
+ return false;
+ }
+
+ const digest = (subject as Error & { digest?: unknown }).digest;
+ if (typeof digest === 'string' && predicate(digest)) {
+ return true;
+ }
+
+ if (depth < MAX_CAUSE_DEPTH && 'cause' in subject) {
+ return hasDigest(subject.cause, predicate, depth + 1);
+ }
+
+ return false;
+}
+
 /**
  * Determines whether input is a Next.js not-found error.
  * https://beta.nextjs.org/docs/api-reference/notfound#notfound
  */
 export function isNotFoundNavigationError(subject: unknown): boolean {
- return (
- isError(subject) &&
- ['NEXT_NOT_FOUND', 'NEXT_HTTP_ERROR_FALLBACK;404'].includes(
- (subject as Error & { digest?: unknown }).digest as string,
- )
- );
+ return hasDigest(subject, digest => ['NEXT_NOT_FOUND', 'NEXT_HTTP_ERROR_FALLBACK;404'].includes(digest));
 }
 
 /**
  * Determines whether input is a Next.js redirect error.
  * https://beta.nextjs.org/docs/api-reference/redirect#redirect
  */
 export function isRedirectNavigationError(subject: unknown): boolean {
- return (
- isError(subject) &&
- typeof (subject as Error & { digest?: unknown }).digest === 'string' &&
- (subject as Error & { digest: string }).digest.startsWith('NEXT_REDIRECT;') // a redirect digest looks like "NEXT_REDIRECT;[redirect path]"
- );
+ // a redirect digest looks like "NEXT_REDIRECT;[redirect path]"
+ return hasDigest(subject, digest => digest.startsWith('NEXT_REDIRECT;'));
+}
+
+const PRERENDER_CONTROL_FLOW_DIGESTS = [
+ // Next.js hands out promises that never settle (e.g. from `fetch()` under Cache Components) and rejects
+ // them once the prerender is aborted. React discards them - anything else observing them must ignore them.
+ 'HANGING_PROMISE_REJECTION',
+ // Thrown to abort a prerender the moment dynamic data is accessed.
+ 'NEXT_PRERENDER_INTERRUPTED',
+ // Thrown to bail out of static generation into dynamic rendering.
+ 'DYNAMIC_SERVER_USAGE',
+ // Thrown by `next/dynamic` to bail out of SSR into client-side rendering.
+ 'BAILOUT_TO_CLIENT_SIDE_RENDERING',
+];
+
+/**
+ * Determines whether input is one of the errors Next.js throws to steer rendering rather than to signal a failure.
+ *
+ * This mirrors the non-navigation half of Next.js' `unstable_rethrow`, which is the contract any code wrapping
+ * user land in a `try`/`catch` has to honor.
+ * https://nextjs.org/docs/app/api-reference/functions/unstable_rethrow
+ */
+export function isPrerenderControlFlowError(subject: unknown): boolean {
+ return hasDigest(subject, digest => PRERENDER_CONTROL_FLOW_DIGESTS.includes(digest));
 }

packages/nextjs/src/common/withServerActionInstrumentation.ts

@@ -15,7 +15,11 @@ import {
 } from '@sentry/core';
 import { flushSafelyWithTimeout, waitUntil } from '../common/utils/responseEnd';
 import { DEBUG_BUILD } from './debug-build';
-import { isNotFoundNavigationError, isRedirectNavigationError } from './nextNavigationErrorUtils';
+import {
+ isNotFoundNavigationError,
+ isPrerenderControlFlowError,
+ isRedirectNavigationError,
+} from './nextNavigationErrorUtils';
 import { SENTRY_SEGMENT_NAME_SOURCE, SENTRY_KIND, SENTRY_OP } from '@sentry/conventions/attributes';
 import { FUNCTION } from '@sentry/conventions/op';
 
@@ -134,6 +138,12 @@ async function withServerActionInstrumentationImplementation<A extends (...args:
  // `internal_error`
  span.setStatus({ code: SPAN_STATUS_OK });
  span.end();
+ } else if (isPrerenderControlFlowError(error)) {
+ // Next.js only throws these from a prerender scope and server actions run in a request
+ // scope, so this is not reachable today. It is here because `unstable_rethrow` defines
+ // the contract for anything catching user land errors, without carving out actions.
+ span.setStatus({ code: SPAN_STATUS_OK });
+ span.end();
  } else {
  span.setStatus({ code: SPAN_STATUS_ERROR, message: 'internal_error' });
  captureException(error, {

packages/nextjs/src/common/wrapGenerationFunctionWithSentry.ts

@@ -9,7 +9,11 @@ import {
  winterCGHeadersToDict,
 } from '@sentry/core';
 import type { GenerationFunctionContext } from '../common/types';
-import { isNotFoundNavigationError, isRedirectNavigationError } from './nextNavigationErrorUtils';
+import {
+ isNotFoundNavigationError,
+ isPrerenderControlFlowError,
+ isRedirectNavigationError,
+} from './nextNavigationErrorUtils';
 import { flushSafelyWithTimeout, waitUntil } from './utils/responseEnd';
 
 /**
@@ -45,34 +49,39 @@ export function wrapGenerationFunctionWithSentry<F extends (...args: any[]) => a
  error => {
  const span = getActiveSpan();
  const { componentRoute, componentType, generationFunctionIdentifier } = context;
- let shouldCapture = true;
  isolationScope.setTransactionName(`${componentType}.${generationFunctionIdentifier} (${componentRoute})`);
 
- if (span) {
- if (isNotFoundNavigationError(error)) {
- // We don't want to report "not-found"s
- shouldCapture = false;
- span.setStatus({ code: SPAN_STATUS_ERROR, message: 'not_found' });
- } else if (isRedirectNavigationError(error)) {
- // We don't want to report redirects
- shouldCapture = false;
- span.setStatus({ code: SPAN_STATUS_OK });
- } else {
- span.setStatus({ code: SPAN_STATUS_ERROR, message: 'internal_error' });
- }
+ // Next.js uses thrown errors for control flow. Whether or not we happen to have an active span here
+ // must not decide if we report them, so these checks deliberately run outside of the span handling.
+ if (isNotFoundNavigationError(error)) {
+ // We don't want to report "not-found"s
+ span?.setStatus({ code: SPAN_STATUS_ERROR, message: 'not_found' });
+ return;
  }
 
- if (shouldCapture) {
-captureException(error, {
- mechanism: {
- handled: false,
- type: 'auto.function.nextjs.generation_function',
- data: {
- function: generationFunctionIdentifier,
- },
- },
-});
+ if (isRedirectNavigationError(error)) {
+// We don't want to report redirects
+span?.setStatus({ code: SPAN_STATUS_OK });
+return;
+}
+
+if (isPrerenderControlFlowError(error)) {
+// Next.js aborts prerenders by rejecting the promises it handed out. React discards those rejections,
+// so they are expected, do not affect the response, and must not be reported.
+return;
  }
+
+ span?.setStatus({ code: SPAN_STATUS_ERROR, message: 'internal_error' });
+
+ captureException(error, {
+ mechanism: {
+ handled: false,
+ type: 'auto.function.nextjs.generation_function',
+ data: {
+ function: generationFunctionIdentifier,
+ },
+ },
+ });
  },
  () => {
  waitUntil(flushSafelyWithTimeout());

packages/nextjs/src/common/wrapRouteHandlerWithSentry.ts

@@ -16,7 +16,11 @@ import {
  withIsolationScope,
  withScope,
 } from '@sentry/core';
-import { isNotFoundNavigationError, isRedirectNavigationError } from './nextNavigationErrorUtils';
+import {
+ isNotFoundNavigationError,
+ isPrerenderControlFlowError,
+ isRedirectNavigationError,
+} from './nextNavigationErrorUtils';
 import type { RouteHandlerContext } from './types';
 import { flushSafelyWithTimeout, waitUntil } from './utils/responseEnd';
 import { commonObjectToIsolationScope } from './utils/tracingUtils';
@@ -89,6 +93,9 @@ export function wrapRouteHandlerWithSentry<F extends (...args: any[]) => any>(
  if (rootSpan) {
  setHttpStatus(rootSpan, 404);
  }
+ } else if (isPrerenderControlFlowError(error)) {
+ // Next.js aborts prerenders by rejecting the promises it handed out. React discards those
+ // rejections, so they are expected, do not affect the response, and must not be reported.
  } else {
  const errorStatus = { code: SPAN_STATUS_ERROR, message: 'internal_error' } as const;
  activeSpan?.setStatus(errorStatus);

packages/nextjs/src/common/wrapServerComponentWithSentry.ts

@@ -8,7 +8,11 @@ import {
  SPAN_STATUS_OK,
  winterCGHeadersToDict,
 } from '@sentry/core';
-import { isNotFoundNavigationError, isRedirectNavigationError } from '../common/nextNavigationErrorUtils';
+import {
+ isNotFoundNavigationError,
+ isPrerenderControlFlowError,
+ isRedirectNavigationError,
+} from '../common/nextNavigationErrorUtils';
 import type { ServerComponentContext } from '../common/types';
 import { flushSafelyWithTimeout, waitUntil } from '../common/utils/responseEnd';
 
@@ -40,31 +44,36 @@ export function wrapServerComponentWithSentry<F extends (...args: any[]) => any>
  error => {
  const span = getActiveSpan();
  const { componentRoute, componentType } = context;
- let shouldCapture = true;
  isolationScope.setTransactionName(`${componentType} Server Component (${componentRoute})`);
 
-if (span) {
-if (isNotFoundNavigationError(error)) {
- // We don't want to report "not-found"s
- shouldCapture = false;
-span.setStatus({ code: SPAN_STATUS_ERROR, message: 'not_found' });
-} else if (isRedirectNavigationError(error)) {
- // We don't want to report redirects
- shouldCapture = false;
- span.setStatus({ code: SPAN_STATUS_OK });
-} else {
-span.setStatus({ code: SPAN_STATUS_ERROR, message: 'internal_error' });
-}
+// Next.js uses thrown errors for control flow. Whether or not we happen to have an active span here
+// must not decide if we report them, so these checks deliberately run outside of the span handling.
+if (isNotFoundNavigationError(error)) {
+// We don't want to report "not-found"s
+ span?.setStatus({ code: SPAN_STATUS_ERROR, message: 'not_found' });
+return;
+}
+
+if (isRedirectNavigationError(error)) {
+// We don't want to report redirects
+ span?.setStatus({ code: SPAN_STATUS_OK });
+return;
  }
 
- if (shouldCapture) {
- captureException(error, {
- mechanism: {
- handled: false,
- type: 'auto.function.nextjs.server_component',
- },
- });
+ if (isPrerenderControlFlowError(error)) {
+ // Next.js aborts prerenders by rejecting the promises it handed out. React discards those rejections,
+ // so they are expected, do not affect the response, and must not be reported.
+ return;
  }
+
+ span?.setStatus({ code: SPAN_STATUS_ERROR, message: 'internal_error' });
+
+ captureException(error, {
+ mechanism: {
+ handled: false,
+ type: 'auto.function.nextjs.server_component',
+ },
+ });
  },
  () => {
  waitUntil(flushSafelyWithTimeout());