gracefully handle client router segment mismatches

packages/next/src/client/components/router-reducer/handle-segment-mismatch.ts

@@ -0,0 +1,28 @@
+import type { FlightRouterState } from '../../../server/app-render/types'
+import { handleExternalUrl } from './reducers/navigate-reducer'
+import type {
+  ReadonlyReducerState,
+  ReducerActions,
+} from './router-reducer-types'
+
+/**
+ * Handles the case where the client router attempted to patch the tree but, due to a mismatch, the patch failed.
+ * This will perform an MPA navigation to return the router to a valid state.
+ */
+export function handleSegmentMismatch(
+  state: ReadonlyReducerState,
+  action: ReducerActions,
+  treePatch: FlightRouterState
+) {
+  if (process.env.NODE_ENV === 'development') {
+    console.warn(
+      'Performing hard navigation because your application experienced an unrecoverable error. If this keeps occurring, please file a Next.js issue.\n\n' +
+        'Reason: Segment mismatch\n' +
+        `Last Action: ${action.type}\n\n` +
+        `Current Tree: ${JSON.stringify(state.tree)}\n\n` +
+        `Tree Patch Payload: ${JSON.stringify(treePatch)}`
+    )
+  }
+
+  return handleExternalUrl(state, {}, state.canonicalUrl, true)
+}

packages/next/src/client/components/router-reducer/reducers/fast-refresh-reducer.ts

@@ -13,6 +13,7 @@ import { handleMutable } from '../handle-mutable'
 import { applyFlightData } from '../apply-flight-data'
 import type { CacheNode } from '../../../../shared/lib/app-router-context.shared-runtime'
 import { createEmptyCacheNode } from '../../app-router'
+import { handleSegmentMismatch } from '../handle-segment-mismatch'
 
 // A version of refresh reducer that keeps the cache around instead of wiping all of it.
 function fastRefreshReducerImpl(
@@ -71,7 +72,7 @@ function fastRefreshReducerImpl(
         )
 
         if (newTree === null) {
-          throw new Error('SEGMENT MISMATCH')
+          return handleSegmentMismatch(state, action, treePatch)
         }
 
         if (isNavigatingToNewRootLayout(currentTree, newTree)) {

packages/next/src/client/components/router-reducer/reducers/refresh-reducer.ts

@@ -13,6 +13,7 @@ import { handleMutable } from '../handle-mutable'
 import type { CacheNode } from '../../../../shared/lib/app-router-context.shared-runtime'
 import { fillLazyItemsTillLeafWithHead } from '../fill-lazy-items-till-leaf-with-head'
 import { createEmptyCacheNode } from '../../app-router'
+import { handleSegmentMismatch } from '../handle-segment-mismatch'
 
 export function refreshReducer(
   state: ReadonlyReducerState,
@@ -69,7 +70,7 @@ export function refreshReducer(
         )
 
         if (newTree === null) {
-          throw new Error('SEGMENT MISMATCH')
+          return handleSegmentMismatch(state, action, treePatch)
         }
 
         if (isNavigatingToNewRootLayout(currentTree, newTree)) {

packages/next/src/client/components/router-reducer/reducers/server-action-reducer.ts

@@ -38,6 +38,7 @@ import { handleMutable } from '../handle-mutable'
 import { fillLazyItemsTillLeafWithHead } from '../fill-lazy-items-till-leaf-with-head'
 import { createEmptyCacheNode } from '../../app-router'
 import { extractPathFromFlightRouterState } from '../compute-changed-path'
+import { handleSegmentMismatch } from '../handle-segment-mismatch'
 
 type FetchServerActionResult = {
   redirectLocation: URL | undefined
@@ -224,7 +225,7 @@ export function serverActionReducer(
         )
 
         if (newTree === null) {
-          throw new Error('SEGMENT MISMATCH')
+          return handleSegmentMismatch(state, action, treePatch)
         }
 
         if (isNavigatingToNewRootLayout(currentTree, newTree)) {

packages/next/src/client/components/router-reducer/reducers/server-patch-reducer.test.tsx

@@ -501,4 +501,62 @@ describe('serverPatchReducer', () => {
       }
     `)
   })
+
+  it("should gracefully recover if the server patch doesn't match the current tree", async () => {
+    const initialTree = getInitialRouterStateTree()
+    const initialCanonicalUrl = '/linking'
+    const children = (
+      <html>
+        <head></head>
+        <body>Root layout</body>
+      </html>
+    )
+
+    const state = createInitialRouterState({
+      buildId,
+      initialTree,
+      initialHead: null,
+      initialCanonicalUrl,
+      initialSeedData: ['', {}, children],
+      initialParallelRoutes: new Map(),
+      isServer: false,
+      location: new URL('/linking/about', 'https://localhost') as any,
+    })
+
+    const action: ServerPatchAction = {
+      type: ACTION_SERVER_PATCH,
+      // this flight data is intentionally completely unrelated to the existing tree
+      flightData: [
+        [
+          'children',
+          'tree-patch-failure',
+          'children',
+          'new-page',
+          ['new-page', { children: ['__PAGE__', {}] }],
+          null,
+          null,
+        ],
+      ],
+      previousTree: [
+        '',
+        {
+          children: [
+            'linking',
+            {
+              children: ['about', { children: ['', {}] }],
+            },
+          ],
+        },
+        undefined,
+        undefined,
+        true,
+      ],
+      overrideCanonicalUrl: undefined,
+    }
+
+    const newState = await serverPatchReducer(state, action)
+    expect(newState.pushRef.pendingPush).toBe(true)
+    expect(newState.pushRef.mpaNavigation).toBe(true)
+    expect(newState.canonicalUrl).toBe('/linking/about')
+  })
 })

packages/next/src/client/components/router-reducer/reducers/server-patch-reducer.ts

@@ -12,6 +12,7 @@ import { applyFlightData } from '../apply-flight-data'
 import { handleMutable } from '../handle-mutable'
 import type { CacheNode } from '../../../../shared/lib/app-router-context.shared-runtime'
 import { createEmptyCacheNode } from '../../app-router'
+import { handleSegmentMismatch } from '../handle-segment-mismatch'
 
 export function serverPatchReducer(
   state: ReadonlyReducerState,
@@ -49,7 +50,7 @@ export function serverPatchReducer(
     )
 
     if (newTree === null) {
-      throw new Error('SEGMENT MISMATCH')
+      return handleSegmentMismatch(state, action, treePatch)
     }
 
     if (isNavigatingToNewRootLayout(currentTree, newTree)) {