fix(react): Patch spanEnd for potentially cancelled lazy-route transactions (#17962)

Fixes an issue where `pageload` and `navigation` transactions have
incorrect (URL-based or wildcard-based) names when the span is cancelled
early before lazy routes finish loading.

This occurs when `document.hidden` triggers early span cancellation
(e.g., user switches tabs during page load). In React Router
applications with lazy routes, the parameterized route information may
not be available yet when the span ends, resulting in transaction names
like `/user/123/edit` (URL-based) or `/projects/*/views/*`
(wildcard-based) instead of the correct parameterized route like
`/user/:id/edit` or `/projects/:projectId/views/:viewId`.

This fix patches `span.end()` to perform a final route resolution check
before the span is sent, using the live global `allRoutes` Set to
capture any lazy routes that loaded after the span was created but
before it ended.

Author: onurtemizkan

dev-packages/e2e-tests/test-applications/react-router-7-lazy-routes/tests/transactions.test.ts

@@ -377,3 +377,124 @@ test('Allows legitimate POP navigation (back/forward) after pageload completes',
   expect(backNavigationEvent.transaction).toBe('/');
   expect(backNavigationEvent.contexts?.trace?.op).toBe('navigation');
 });
+
+test('Updates pageload transaction name correctly when span is cancelled early (document.hidden simulation)', async ({
+  page,
+}) => {
+  const transactionPromise = waitForTransaction('react-router-7-lazy-routes', async transactionEvent => {
+    return (
+      !!transactionEvent?.transaction &&
+      transactionEvent.contexts?.trace?.op === 'pageload' &&
+      transactionEvent.transaction === '/lazy/inner/:id/:anotherId/:someAnotherId'
+    );
+  });
+
+  // Set up the page to simulate document.hidden before navigation
+  await page.addInitScript(() => {
+    // Wait a bit for Sentry to initialize and start the pageload span
+    setTimeout(() => {
+      // Override document.hidden to simulate tab switching
+      Object.defineProperty(document, 'hidden', {
+        configurable: true,
+        get: function () {
+          return true;
+        },
+      });
+
+      // Dispatch visibilitychange event to trigger the idle span cancellation logic
+      document.dispatchEvent(new Event('visibilitychange'));
+    }, 100); // Small delay to ensure the span has started
+  });
+
+  // Navigate to the lazy route URL
+  await page.goto('/lazy/inner/1/2/3');
+
+  const event = await transactionPromise;
+
+  // Verify the lazy route content eventually loads (even though span was cancelled early)
+  const lazyRouteContent = page.locator('id=innermost-lazy-route');
+  await expect(lazyRouteContent).toBeVisible();
+
+  // Validate that the transaction event has the correct parameterized route name
+  // even though the span was cancelled early due to document.hidden
+  expect(event.transaction).toBe('/lazy/inner/:id/:anotherId/:someAnotherId');
+  expect(event.type).toBe('transaction');
+  expect(event.contexts?.trace?.op).toBe('pageload');
+
+  // Check if the span was indeed cancelled (should have idle_span_finish_reason attribute)
+  const idleSpanFinishReason = event.contexts?.trace?.data?.['sentry.idle_span_finish_reason'];
+  if (idleSpanFinishReason) {
+    // If the span was cancelled due to visibility change, verify it still got the right name
+    expect(['externalFinish', 'cancelled']).toContain(idleSpanFinishReason);
+  }
+});
+
+test('Updates navigation transaction name correctly when span is cancelled early (document.hidden simulation)', async ({
+  page,
+}) => {
+  // First go to home page
+  await page.goto('/');
+
+  const navigationPromise = waitForTransaction('react-router-7-lazy-routes', async transactionEvent => {
+    return (
+      !!transactionEvent?.transaction &&
+      transactionEvent.contexts?.trace?.op === 'navigation' &&
+      transactionEvent.transaction === '/lazy/inner/:id/:anotherId/:someAnotherId'
+    );
+  });
+
+  // Set up a listener to simulate document.hidden after clicking the navigation link
+  await page.evaluate(() => {
+    // Override document.hidden to simulate tab switching
+    let hiddenValue = false;
+    Object.defineProperty(document, 'hidden', {
+      configurable: true,
+      get: function () {
+        return hiddenValue;
+      },
+    });
+
+    // Listen for clicks on the navigation link and simulate document.hidden shortly after
+    document.addEventListener(
+      'click',
+      () => {
+        setTimeout(() => {
+          hiddenValue = true;
+          // Dispatch visibilitychange event to trigger the idle span cancellation logic
+          document.dispatchEvent(new Event('visibilitychange'));
+        }, 50); // Small delay to ensure the navigation span has started
+      },
+      { once: true },
+    );
+  });
+
+  // Click the navigation link to navigate to the lazy route
+  const navigationLink = page.locator('id=navigation');
+  await expect(navigationLink).toBeVisible();
+  await navigationLink.click();
+
+  const event = await navigationPromise;
+
+  // Verify the lazy route content eventually loads (even though span was cancelled early)
+  const lazyRouteContent = page.locator('id=innermost-lazy-route');
+  await expect(lazyRouteContent).toBeVisible();
+
+  // Validate that the transaction event has the correct parameterized route name
+  // even though the span was cancelled early due to document.hidden
+  expect(event.transaction).toBe('/lazy/inner/:id/:anotherId/:someAnotherId');
+  expect(event.type).toBe('transaction');
+  expect(event.contexts?.trace?.op).toBe('navigation');
+
+  // Check if the span was indeed cancelled (should have cancellation_reason attribute or idle_span_finish_reason)
+  const cancellationReason = event.contexts?.trace?.data?.['sentry.cancellation_reason'];
+  const idleSpanFinishReason = event.contexts?.trace?.data?.['sentry.idle_span_finish_reason'];
+
+  // Verify that the span was cancelled due to document.hidden
+  if (cancellationReason) {
+    expect(cancellationReason).toBe('document.hidden');
+  }
+
+  if (idleSpanFinishReason) {
+    expect(['externalFinish', 'cancelled']).toContain(idleSpanFinishReason);
+  }
+});

packages/react/src/reactrouter-compat-utils/instrumentation.tsx

@@ -8,7 +8,7 @@ import {
   startBrowserTracingPageLoadSpan,
   WINDOW,
 } from '@sentry/browser';
-import type { Client, Integration, Span, TransactionSource } from '@sentry/core';
+import type { Client, Integration, Span } from '@sentry/core';
 import {
   addNonEnumerableProperty,
   debug,
@@ -41,14 +41,7 @@ import type {
   UseRoutes,
 } from '../types';
 import { checkRouteForAsyncHandler } from './lazy-routes';
-import {
-  getNormalizedName,
-  initializeRouterUtils,
-  locationIsInsideDescendantRoute,
-  prefixWithSlash,
-  rebuildRoutePathFromAllRoutes,
-  resolveRouteNameAndSource,
-} from './utils';
+import { initializeRouterUtils, resolveRouteNameAndSource } from './utils';
 
 let _useEffect: UseEffect;
 let _useLocation: UseLocation;
@@ -668,14 +661,19 @@ export function handleNavigation(opts: {
 
     // Cross usage can result in multiple navigation spans being created without this check
     if (!isAlreadyInNavigationSpan) {
-      startBrowserTracingNavigationSpan(client, {
+      const navigationSpan = startBrowserTracingNavigationSpan(client, {
         name,
         attributes: {
           [SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: source,
           [SEMANTIC_ATTRIBUTE_SENTRY_OP]: 'navigation',
           [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: `auto.navigation.react.reactrouter_v${version}`,
         },
       });
+
+      // Patch navigation span to handle early cancellation (e.g., document.hidden)
+      if (navigationSpan) {
+        patchNavigationSpanEnd(navigationSpan, location, routes, basename, allRoutes);
+      }
     }
   }
 }
@@ -729,29 +727,104 @@ function updatePageloadTransaction({
     : (_matchRoutes(allRoutes || routes, location, basename) as unknown as RouteMatch[]);
 
   if (branches) {
-    let name,
-      source: TransactionSource = 'url';
-
-    const isInDescendantRoute = locationIsInsideDescendantRoute(location, allRoutes || routes);
-
-    if (isInDescendantRoute) {
-      name = prefixWithSlash(rebuildRoutePathFromAllRoutes(allRoutes || routes, location));
-      source = 'route';
-    }
-
-    if (!isInDescendantRoute || !name) {
-      [name, source] = getNormalizedName(routes, location, branches, basename);
-    }
+    const [name, source] = resolveRouteNameAndSource(location, routes, allRoutes || routes, branches, basename);
 
     getCurrentScope().setTransactionName(name || '/');
 
     if (activeRootSpan) {
       activeRootSpan.updateName(name);
       activeRootSpan.setAttribute(SEMANTIC_ATTRIBUTE_SENTRY_SOURCE, source);
+
+      // Patch span.end() to ensure we update the name one last time before the span is sent
+      patchPageloadSpanEnd(activeRootSpan, location, routes, basename, allRoutes);
     }
   }
 }
 
+/**
+ * Patches the span.end() method to update the transaction name one last time before the span is sent.
+ * This handles cases where the span is cancelled early (e.g., document.hidden) before lazy routes have finished loading.
+ */
+function patchSpanEnd(
+  span: Span,
+  location: Location,
+  routes: RouteObject[],
+  basename: string | undefined,
+  _allRoutes: RouteObject[] | undefined,
+  spanType: 'pageload' | 'navigation',
+): void {
+  const patchedPropertyName = `__sentry_${spanType}_end_patched__` as const;
+  const hasEndBeenPatched = (span as unknown as Record<string, boolean | undefined>)?.[patchedPropertyName];
+
+  if (hasEndBeenPatched || !span.end) {
+    return;
+  }
+
+  const originalEnd = span.end.bind(span);
+
+  span.end = function patchedEnd(...args) {
+    try {
+      // Only update if the span source is not already 'route' (i.e., it hasn't been parameterized yet)
+      const spanJson = spanToJSON(span);
+      const currentSource = spanJson.data?.[SEMANTIC_ATTRIBUTE_SENTRY_SOURCE];
+      if (currentSource !== 'route') {
+        // Last chance to update the transaction name with the latest route info
+        // Use the live global allRoutes Set to include any lazy routes loaded after patching
+        const currentAllRoutes = Array.from(allRoutes);
+        const branches = _matchRoutes(
+          currentAllRoutes.length > 0 ? currentAllRoutes : routes,
+          location,
+          basename,
+        ) as unknown as RouteMatch[];
+
+        if (branches) {
+          const [name, source] = resolveRouteNameAndSource(
+            location,
+            routes,
+            currentAllRoutes.length > 0 ? currentAllRoutes : routes,
+            branches,
+            basename,
+          );
+
+          // Only update if we have a valid name
+          if (name && (spanType === 'pageload' || !spanJson.timestamp)) {
+            span.updateName(name);
+            span.setAttribute(SEMANTIC_ATTRIBUTE_SENTRY_SOURCE, source);
+          }
+        }
+      }
+    } catch (error) {
+      // Silently catch errors to ensure span.end() is always called
+      DEBUG_BUILD && debug.warn(`Error updating span details before ending: ${error}`);
+    }
+
+    return originalEnd(...args);
+  };
+
+  // Mark this span as having its end() method patched to prevent duplicate patching
+  addNonEnumerableProperty(span as unknown as Record<string, boolean>, patchedPropertyName, true);
+}
+
+function patchPageloadSpanEnd(
+  span: Span,
+  location: Location,
+  routes: RouteObject[],
+  basename: string | undefined,
+  _allRoutes: RouteObject[] | undefined,
+): void {
+  patchSpanEnd(span, location, routes, basename, _allRoutes, 'pageload');
+}
+
+function patchNavigationSpanEnd(
+  span: Span,
+  location: Location,
+  routes: RouteObject[],
+  basename: string | undefined,
+  _allRoutes: RouteObject[] | undefined,
+): void {
+  patchSpanEnd(span, location, routes, basename, _allRoutes, 'navigation');
+}
+
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function createV6CompatibleWithSentryReactRouterRouting<P extends Record<string, any>, R extends React.FC<P>>(
   Routes: R,

packages/react/test/reactrouter-compat-utils/instrumentation.test.tsx

@@ -142,6 +142,43 @@ describe('reactrouter-compat-utils/instrumentation', () => {
       expect(typeof integration.afterAllSetup).toBe('function');
     });
   });
+
+  describe('span.end() patching for early cancellation', () => {
+    it('should update transaction name when span.end() is called during cancellation', () => {
+      const mockEnd = vi.fn();
+      let patchedEnd: ((...args: any[]) => any) | null = null;
+
+      const updateNameMock = vi.fn();
+      const setAttributeMock = vi.fn();
+
+      const testSpan = {
+        updateName: updateNameMock,
+        setAttribute: setAttributeMock,
+        get end() {
+          return patchedEnd || mockEnd;
+        },
+        set end(fn: (...args: any[]) => any) {
+          patchedEnd = fn;
+        },
+      } as unknown as Span;
+
+      // Simulate the patching behavior
+      const originalEnd = testSpan.end.bind(testSpan);
+      (testSpan as any).end = function patchedEndFn(...args: any[]) {
+        // This simulates what happens in the actual implementation
+        updateNameMock('Updated Route');
+        setAttributeMock('sentry.source', 'route');
+        return originalEnd(...args);
+      };
+
+      // Call the patched end
+      testSpan.end(12345);
+
+      expect(updateNameMock).toHaveBeenCalledWith('Updated Route');
+      expect(setAttributeMock).toHaveBeenCalledWith('sentry.source', 'route');
+      expect(mockEnd).toHaveBeenCalledWith(12345);
+    });
+  });
 });
 
 describe('addRoutesToAllRoutes', () => {