fix(nextjs): Don't inject trace meta tags when Cache Components is enabled (#21141)

Problem is that we do not have a consistent way of detecting stale meta
tags so we rather disable them for `cacheComponents`.

This stops the SDK from enabling Next's
`experimental.clientTraceMetadata` (`sentry-trace`/`baggage`) when
`cacheComponents` is enabled. With no meta tags injected, the browser
pageload starts a fresh, self-contained trace instead of stitching onto
a stale one. Apps that don't use Cache Components are unaffected.

closes
https://linear.app/getsentry/issue/JS-2782/cachecomponents-setup-breaks-meta-tag-injection

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: chargome

dev-packages/e2e-tests/test-applications/nextjs-16-cacheComponents/app/pageload-tracing/page.tsx

@@ -0,0 +1,37 @@
+import { Suspense } from 'react';
+import { headers } from 'next/headers';
+import * as Sentry from '@sentry/nextjs';
+
+async function CachedContent() {
+  const getTodos = async () => {
+    return Sentry.startSpan({ name: 'getTodos', op: 'get.todos' }, async () => {
+      'use cache';
+      await new Promise(resolve => setTimeout(resolve, 100));
+      return [1, 2, 3, 4, 5];
+    });
+  };
+
+  const todos = await getTodos();
+
+  return <div id="todos-fetched">Todos fetched: {todos.length}</div>;
+}
+
+async function DynamicContent() {
+  await headers();
+  return (
+    <>
+      <CachedContent />
+    </>
+  );
+}
+
+export default function Page() {
+  return (
+    <>
+      <h1>Cache Pageload Tracing</h1>
+      <Suspense fallback={<div>Loading...</div>}>
+        <DynamicContent />
+      </Suspense>
+    </>
+  );
+}

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

@@ -26,7 +26,7 @@
     "@sentry/nextjs": "file:../../packed/sentry-nextjs-packed.tgz",
     "@sentry/core": "file:../../packed/sentry-core-packed.tgz",
     "import-in-the-middle": "^1",
-    "next": "16.2.3",
+    "next": "^16",
     "react": "19.1.0",
     "react-dom": "19.1.0",
     "require-in-the-middle": "^7",

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

@@ -81,6 +81,38 @@ test('Should generate metadata async', async ({ page }) => {
   await expect(page).toHaveTitle('Product: 1');
 });
 
+test('Prerendered shell does not stitch the pageload onto a stale trace', async ({ page }) => {
+  const serverTxPromise = waitForTransaction('nextjs-16-cacheComponents', async transactionEvent => {
+    return (
+      transactionEvent.contexts?.trace?.op === 'http.server' && transactionEvent.transaction === 'GET /pageload-tracing'
+    );
+  });
+
+  const pageloadTxPromise = waitForTransaction('nextjs-16-cacheComponents', async transactionEvent => {
+    return transactionEvent.contexts?.trace?.op === 'pageload' && transactionEvent.transaction === '/pageload-tracing';
+  });
+
+  await page.goto('/pageload-tracing');
+
+  await expect(page.locator('#todos-fetched')).toHaveText('Todos fetched: 5');
+
+  const [serverTx, pageloadTx] = await Promise.all([serverTxPromise, pageloadTxPromise]);
+
+  const serverTraceId = serverTx.contexts?.trace?.trace_id;
+  const pageloadTraceId = pageloadTx.contexts?.trace?.trace_id;
+
+  // Under Cache Components the shell is prerendered and rendered in a context detached from the
+  // runtime server request, so a `sentry-trace` meta tag would carry a stale/unrelated trace. The
+  // SDK therefore does not enable the trace meta tags, and the browser pageload starts a fresh trace
+  // instead of stitching onto a trace that doesn't match the server request.
+  expect(pageloadTraceId).toBeTruthy();
+  expect(serverTraceId).not.toBe(pageloadTraceId);
+
+  // No trace meta tags should be injected when Cache Components is enabled.
+  expect(await page.locator('meta[name="sentry-trace"]').count()).toBe(0);
+  expect(await page.locator('meta[name="baggage"]').count()).toBe(0);
+});
+
 test('Should prerender a page that captures an exception in generateMetadata', async ({ page }) => {
   await page.goto('/capture-metadata');
 

dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/.gitignore

@@ -0,0 +1,44 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+# Sentry Config File
+.env.sentry-build-plugin

dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/cache/page.tsx

@@ -0,0 +1,25 @@
+import { Suspense } from 'react';
+import * as Sentry from '@sentry/nextjs';
+
+export default function Page() {
+  return (
+    <>
+      <h1>This will be pre-rendered</h1>
+      <DynamicContent />
+    </>
+  );
+}
+
+async function DynamicContent() {
+  const getTodos = async () => {
+    return Sentry.startSpan({ name: 'getTodos', op: 'get.todos' }, async () => {
+      'use cache';
+      await new Promise(resolve => setTimeout(resolve, 100));
+      return [1, 2, 3, 4, 5];
+    });
+  };
+
+  const todos = await getTodos();
+
+  return <div id="todos-fetched">Todos fetched: {todos.length}</div>;
+}

dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/favicon.ico

@@ -0,0 +1,23 @@
+'use client';
+
+import * as Sentry from '@sentry/nextjs';
+import NextError from 'next/error';
+import { useEffect } from 'react';
+
+export default function GlobalError({ error }: { error: Error & { digest?: string } }) {
+  useEffect(() => {
+    Sentry.captureException(error);
+  }, [error]);
+
+  return (
+    <html>
+      <body>
+        {/* `NextError` is the default Next.js error page component. Its type
+        definition requires a `statusCode` prop. However, since the App Router
+        does not expose status codes for errors, we simply pass 0 to render a
+        generic error message. */}
+        <NextError statusCode={0} />
+      </body>
+    </html>
+  );
+}

dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/global-error.tsx

@@ -0,0 +1,7 @@
+export default function Layout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}

dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/layout.tsx

@@ -0,0 +1,37 @@
+import * as Sentry from '@sentry/nextjs';
+
+function fetchPost() {
+  return Promise.resolve({ id: '1', title: 'Post 1' });
+}
+
+export async function generateMetadata() {
+  const { id } = await fetchPost();
+  const product = `Product: ${id}`;
+
+  return {
+    title: product,
+  };
+}
+
+export default function Page() {
+  return (
+    <>
+      <h1>This will be pre-rendered</h1>
+      <DynamicContent />
+    </>
+  );
+}
+
+async function DynamicContent() {
+  const getTodos = async () => {
+    return Sentry.startSpan({ name: 'getTodos', op: 'get.todos' }, async () => {
+      'use cache';
+      await new Promise(resolve => setTimeout(resolve, 100));
+      return [1, 2, 3, 4, 5];
+    });
+  };
+
+  const todos = await getTodos();
+
+  return <div id="todos-fetched">Todos fetched: {todos.length}</div>;
+}

dev-packages/e2e-tests/test-applications/nextjs-16-streaming-cacheComponents/app/metadata-async/page.tsx

@@ -0,0 +1,35 @@
+import * as Sentry from '@sentry/nextjs';
+
+/**
+ * Tests generateMetadata function with cache components, this calls the propagation context to be set
+ * Which will generate and set a trace id in the propagation context, which should trigger the random API error if unpatched
+ * See: https://github.com/getsentry/sentry-javascript/issues/18392
+ */
+export function generateMetadata() {
+  return {
+    title: 'Cache Components Metadata Test',
+  };
+}
+
+export default function Page() {
+  return (
+    <>
+      <h1>This will be pre-rendered</h1>
+      <DynamicContent />
+    </>
+  );
+}
+
+async function DynamicContent() {
+  const getTodos = async () => {
+    return Sentry.startSpan({ name: 'getTodos', op: 'get.todos' }, async () => {
+      'use cache';
+      await new Promise(resolve => setTimeout(resolve, 100));
+      return [1, 2, 3, 4, 5];
+    });
+  };
+
+  const todos = await getTodos();
+
+  return <div id="todos-fetched">Todos fetched: {todos.length}</div>;
+}