fix(router-core,ssr-client): Catch errors thrown during hydrate

e2e/react-start/basic/src/routeTree.gen.ts

@@ -34,6 +34,7 @@ import { Route as SearchParamsDefaultRouteImport } from './routes/search-params/
 import { Route as RedirectTargetRouteImport } from './routes/redirect/$target'
 import { Route as PostsPostIdRouteImport } from './routes/posts.$postId'
 import { Route as NotFoundViaLoaderRouteImport } from './routes/not-found/via-loader'
+import { Route as NotFoundViaHeadRouteImport } from './routes/not-found/via-head'
 import { Route as NotFoundViaBeforeLoadRouteImport } from './routes/not-found/via-beforeLoad'
 import { Route as ApiUsersRouteImport } from './routes/api.users'
 import { Route as LayoutLayout2RouteImport } from './routes/_layout/_layout-2'
@@ -169,6 +170,11 @@ const NotFoundViaLoaderRoute = NotFoundViaLoaderRouteImport.update({
   path: '/via-loader',
   getParentRoute: () => NotFoundRouteRoute,
 } as any)
+const NotFoundViaHeadRoute = NotFoundViaHeadRouteImport.update({
+  id: '/via-head',
+  path: '/via-head',
+  getParentRoute: () => NotFoundRouteRoute,
+} as any)
 const NotFoundViaBeforeLoadRoute = NotFoundViaBeforeLoadRouteImport.update({
   id: '/via-beforeLoad',
   path: '/via-beforeLoad',
@@ -272,6 +278,7 @@ export interface FileRoutesByFullPath {
   '/대한민국': typeof Char45824Char54620Char48124Char44397Route
   '/api/users': typeof ApiUsersRouteWithChildren
   '/not-found/via-beforeLoad': typeof NotFoundViaBeforeLoadRoute
+  '/not-found/via-head': typeof NotFoundViaHeadRoute
   '/not-found/via-loader': typeof NotFoundViaLoaderRoute
   '/posts/$postId': typeof PostsPostIdRoute
   '/redirect/$target': typeof RedirectTargetRouteWithChildren
@@ -307,6 +314,7 @@ export interface FileRoutesByTo {
   '/대한민국': typeof Char45824Char54620Char48124Char44397Route
   '/api/users': typeof ApiUsersRouteWithChildren
   '/not-found/via-beforeLoad': typeof NotFoundViaBeforeLoadRoute
+  '/not-found/via-head': typeof NotFoundViaHeadRoute
   '/not-found/via-loader': typeof NotFoundViaLoaderRoute
   '/posts/$postId': typeof PostsPostIdRoute
   '/search-params/default': typeof SearchParamsDefaultRoute
@@ -347,6 +355,7 @@ export interface FileRoutesById {
   '/_layout/_layout-2': typeof LayoutLayout2RouteWithChildren
   '/api/users': typeof ApiUsersRouteWithChildren
   '/not-found/via-beforeLoad': typeof NotFoundViaBeforeLoadRoute
+  '/not-found/via-head': typeof NotFoundViaHeadRoute
   '/not-found/via-loader': typeof NotFoundViaLoaderRoute
   '/posts/$postId': typeof PostsPostIdRoute
   '/redirect/$target': typeof RedirectTargetRouteWithChildren
@@ -389,6 +398,7 @@ export interface FileRouteTypes {
     | '/대한민국'
     | '/api/users'
     | '/not-found/via-beforeLoad'
+    | '/not-found/via-head'
     | '/not-found/via-loader'
     | '/posts/$postId'
     | '/redirect/$target'
@@ -424,6 +434,7 @@ export interface FileRouteTypes {
     | '/대한민국'
     | '/api/users'
     | '/not-found/via-beforeLoad'
+    | '/not-found/via-head'
     | '/not-found/via-loader'
     | '/posts/$postId'
     | '/search-params/default'
@@ -463,6 +474,7 @@ export interface FileRouteTypes {
     | '/_layout/_layout-2'
     | '/api/users'
     | '/not-found/via-beforeLoad'
+    | '/not-found/via-head'
     | '/not-found/via-loader'
     | '/posts/$postId'
     | '/redirect/$target'
@@ -673,6 +685,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof NotFoundViaLoaderRouteImport
       parentRoute: typeof NotFoundRouteRoute
     }
+    '/not-found/via-head': {
+      id: '/not-found/via-head'
+      path: '/via-head'
+      fullPath: '/not-found/via-head'
+      preLoaderRoute: typeof NotFoundViaHeadRouteImport
+      parentRoute: typeof NotFoundRouteRoute
+    }
     '/not-found/via-beforeLoad': {
       id: '/not-found/via-beforeLoad'
       path: '/via-beforeLoad'
@@ -797,12 +816,14 @@ declare module '@tanstack/react-router' {
 
 interface NotFoundRouteRouteChildren {
   NotFoundViaBeforeLoadRoute: typeof NotFoundViaBeforeLoadRoute
+  NotFoundViaHeadRoute: typeof NotFoundViaHeadRoute
   NotFoundViaLoaderRoute: typeof NotFoundViaLoaderRoute
   NotFoundIndexRoute: typeof NotFoundIndexRoute
 }
 
 const NotFoundRouteRouteChildren: NotFoundRouteRouteChildren = {
   NotFoundViaBeforeLoadRoute: NotFoundViaBeforeLoadRoute,
+  NotFoundViaHeadRoute: NotFoundViaHeadRoute,
   NotFoundViaLoaderRoute: NotFoundViaLoaderRoute,
   NotFoundIndexRoute: NotFoundIndexRoute,
 }

e2e/react-start/basic/src/routes/not-found/index.tsx

@@ -25,6 +25,16 @@ export const Route = createFileRoute('/not-found/')({
             via-loader
           </Link>
         </div>
+        <div className="mb-2">
+          <Link
+            from={Route.fullPath}
+            to="./via-head"
+            preload={preload}
+            data-testid="via-head"
+          >
+            via-head
+          </Link>
+        </div>
       </div>
     )
   },

e2e/react-start/basic/src/routes/not-found/via-head.tsx

@@ -0,0 +1,23 @@
+import { createFileRoute, notFound } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/not-found/via-head')({
+  head: () => {
+    throw notFound()
+  },
+  component: RouteComponent,
+  notFoundComponent: () => {
+    return (
+      <div data-testid="via-head-notFound-component">
+        Not Found "/not-found/via-head"!
+      </div>
+    )
+  },
+})
+
+function RouteComponent() {
+  return (
+    <div data-testid="via-head-route-component" data-server={typeof window}>
+      Hello "/not-found/via-head"!
+    </div>
+  )
+}

e2e/react-start/basic/tests/not-found.spec.ts

@@ -9,6 +9,7 @@ const combinate = (combinateImport as any).default as typeof combinateImport
 test.use({
   whitelistErrors: [
     /Failed to load resource: the server responded with a status of 404/,
+    'Error during route context hydration: {isNotFound: true}',
   ],
 })
 test.describe('not-found', () => {
@@ -24,8 +25,7 @@ test.describe('not-found', () => {
 
   test.describe('throw notFound()', () => {
     const navigationTestMatrix = combinate({
-      // TODO beforeLoad!
-      thrower: [/* 'beforeLoad',*/ 'loader'] as const,
+      thrower: ['beforeLoad', 'head', 'loader'] as const,
       preload: [false, true] as const,
     })
 
@@ -55,9 +55,7 @@ test.describe('not-found', () => {
       })
     })
     const directVisitTestMatrix = combinate({
-      // TODO beforeLoad!
-
-      thrower: [/* 'beforeLoad',*/ 'loader'] as const,
+      thrower: ['beforeLoad', 'head', 'loader'] as const,
     })
 
     directVisitTestMatrix.forEach(({ thrower }) => {

e2e/solid-start/basic/src/routeTree.gen.ts

@@ -31,6 +31,7 @@ import { Route as SearchParamsDefaultRouteImport } from './routes/search-params/
 import { Route as RedirectTargetRouteImport } from './routes/redirect/$target'
 import { Route as PostsPostIdRouteImport } from './routes/posts.$postId'
 import { Route as NotFoundViaLoaderRouteImport } from './routes/not-found/via-loader'
+import { Route as NotFoundViaHeadRouteImport } from './routes/not-found/via-head'
 import { Route as NotFoundViaBeforeLoadRouteImport } from './routes/not-found/via-beforeLoad'
 import { Route as ApiUsersRouteImport } from './routes/api/users'
 import { Route as LayoutLayout2RouteImport } from './routes/_layout/_layout-2'
@@ -156,6 +157,11 @@ const NotFoundViaLoaderRoute = NotFoundViaLoaderRouteImport.update({
   path: '/via-loader',
   getParentRoute: () => NotFoundRouteRoute,
 } as any)
+const NotFoundViaHeadRoute = NotFoundViaHeadRouteImport.update({
+  id: '/via-head',
+  path: '/via-head',
+  getParentRoute: () => NotFoundRouteRoute,
+} as any)
 const NotFoundViaBeforeLoadRoute = NotFoundViaBeforeLoadRouteImport.update({
   id: '/via-beforeLoad',
   path: '/via-beforeLoad',
@@ -244,6 +250,7 @@ export interface FileRoutesByFullPath {
   '/users': typeof UsersRouteWithChildren
   '/api/users': typeof ApiUsersRouteWithChildren
   '/not-found/via-beforeLoad': typeof NotFoundViaBeforeLoadRoute
+  '/not-found/via-head': typeof NotFoundViaHeadRoute
   '/not-found/via-loader': typeof NotFoundViaLoaderRoute
   '/posts/$postId': typeof PostsPostIdRoute
   '/redirect/$target': typeof RedirectTargetRouteWithChildren
@@ -276,6 +283,7 @@ export interface FileRoutesByTo {
   '/stream': typeof StreamRoute
   '/api/users': typeof ApiUsersRouteWithChildren
   '/not-found/via-beforeLoad': typeof NotFoundViaBeforeLoadRoute
+  '/not-found/via-head': typeof NotFoundViaHeadRoute
   '/not-found/via-loader': typeof NotFoundViaLoaderRoute
   '/posts/$postId': typeof PostsPostIdRoute
   '/search-params/default': typeof SearchParamsDefaultRoute
@@ -314,6 +322,7 @@ export interface FileRoutesById {
   '/_layout/_layout-2': typeof LayoutLayout2RouteWithChildren
   '/api/users': typeof ApiUsersRouteWithChildren
   '/not-found/via-beforeLoad': typeof NotFoundViaBeforeLoadRoute
+  '/not-found/via-head': typeof NotFoundViaHeadRoute
   '/not-found/via-loader': typeof NotFoundViaLoaderRoute
   '/posts/$postId': typeof PostsPostIdRoute
   '/redirect/$target': typeof RedirectTargetRouteWithChildren
@@ -352,6 +361,7 @@ export interface FileRouteTypes {
     | '/users'
     | '/api/users'
     | '/not-found/via-beforeLoad'
+    | '/not-found/via-head'
     | '/not-found/via-loader'
     | '/posts/$postId'
     | '/redirect/$target'
@@ -384,6 +394,7 @@ export interface FileRouteTypes {
     | '/stream'
     | '/api/users'
     | '/not-found/via-beforeLoad'
+    | '/not-found/via-head'
     | '/not-found/via-loader'
     | '/posts/$postId'
     | '/search-params/default'
@@ -421,6 +432,7 @@ export interface FileRouteTypes {
     | '/_layout/_layout-2'
     | '/api/users'
     | '/not-found/via-beforeLoad'
+    | '/not-found/via-head'
     | '/not-found/via-loader'
     | '/posts/$postId'
     | '/redirect/$target'
@@ -619,6 +631,13 @@ declare module '@tanstack/solid-router' {
       preLoaderRoute: typeof NotFoundViaLoaderRouteImport
       parentRoute: typeof NotFoundRouteRoute
     }
+    '/not-found/via-head': {
+      id: '/not-found/via-head'
+      path: '/via-head'
+      fullPath: '/not-found/via-head'
+      preLoaderRoute: typeof NotFoundViaHeadRouteImport
+      parentRoute: typeof NotFoundRouteRoute
+    }
     '/not-found/via-beforeLoad': {
       id: '/not-found/via-beforeLoad'
       path: '/via-beforeLoad'
@@ -722,12 +741,14 @@ declare module '@tanstack/solid-router' {
 
 interface NotFoundRouteRouteChildren {
   NotFoundViaBeforeLoadRoute: typeof NotFoundViaBeforeLoadRoute
+  NotFoundViaHeadRoute: typeof NotFoundViaHeadRoute
   NotFoundViaLoaderRoute: typeof NotFoundViaLoaderRoute
   NotFoundIndexRoute: typeof NotFoundIndexRoute
 }
 
 const NotFoundRouteRouteChildren: NotFoundRouteRouteChildren = {
   NotFoundViaBeforeLoadRoute: NotFoundViaBeforeLoadRoute,
+  NotFoundViaHeadRoute: NotFoundViaHeadRoute,
   NotFoundViaLoaderRoute: NotFoundViaLoaderRoute,
   NotFoundIndexRoute: NotFoundIndexRoute,
 }

e2e/solid-start/basic/src/routes/not-found/index.tsx

@@ -25,6 +25,16 @@ export const Route = createFileRoute('/not-found/')({
             via-loader
           </Link>
         </div>
+        <div class="mb-2">
+          <Link
+            from={Route.fullPath}
+            to="./via-head"
+            preload={preload()}
+            data-testid="via-head"
+          >
+            via-head
+          </Link>
+        </div>
       </div>
     )
   },

e2e/solid-start/basic/src/routes/not-found/via-head.tsx

@@ -0,0 +1,23 @@
+import { createFileRoute, notFound } from '@tanstack/solid-router'
+
+export const Route = createFileRoute('/not-found/via-head')({
+  head: () => {
+    throw notFound()
+  },
+  component: RouteComponent,
+  notFoundComponent: () => {
+    return (
+      <div data-testid="via-head-notFound-component">
+        Not Found "/not-found/via-head"!
+      </div>
+    )
+  },
+})
+
+function RouteComponent() {
+  return (
+    <div data-testid="via-head-route-component" data-server={typeof window}>
+      Hello "/not-found/via-head"!
+    </div>
+  )
+}

e2e/solid-start/basic/tests/not-found.spec.ts

@@ -9,6 +9,7 @@ const combinate = (combinateImport as any).default as typeof combinateImport
 test.use({
   whitelistErrors: [
     /Failed to load resource: the server responded with a status of 404/,
+    'Error during route context hydration: {isNotFound: true}',
   ],
 })
 test.describe('not-found', () => {
@@ -24,8 +25,7 @@ test.describe('not-found', () => {
 
   test.describe('throw notFound()', () => {
     const navigationTestMatrix = combinate({
-      // TODO beforeLoad!
-      thrower: [/* 'beforeLoad',*/ 'loader'] as const,
+      thrower: ['beforeLoad', 'head', 'loader'] as const,
       preload: [false, true] as const,
     })
 
@@ -54,9 +54,7 @@ test.describe('not-found', () => {
       })
     })
     const directVisitTestMatrix = combinate({
-      // TODO beforeLoad!
-
-      thrower: [/* 'beforeLoad',*/ 'loader'] as const,
+      thrower: ['beforeLoad', 'head', 'loader'] as const,
     })
 
     directVisitTestMatrix.forEach(({ thrower }) => {

packages/react-router/tests/store-updates-during-navigation.test.tsx

@@ -197,7 +197,7 @@ describe("Store doesn't update *too many* times during navigation", () => {
     // This number should be as small as possible to minimize the amount of work
     // that needs to be done during a navigation.
     // Any change that increases this number should be investigated.
-    expect(updates).toBe(7)
+    expect(updates).toBe(6)
   })
 
   test('hover preload, then navigate, w/ async loaders', async () => {

packages/router-core/src/load-matches.ts

@@ -53,9 +53,18 @@ const resolvePreload = (inner: InnerLoadContext, matchId: string): boolean => {
 const _handleNotFound = (inner: InnerLoadContext, err: NotFoundError) => {
   // Find the route that should handle the not found error
   // First check if a specific route is requested to show the error
-  const routeCursor =
+  let routeCursor =
     inner.router.routesById[err.routeId ?? ''] ?? inner.router.routeTree
 
+  // For BEFORE_LOAD errors, find a parent route with a notFoundComponent that can handle the error
+  if ((err as any).routerCode === 'BEFORE_LOAD' && routeCursor.parentRoute) {
+    while (routeCursor.parentRoute && !routeCursor.options.notFoundComponent) {
+      routeCursor = routeCursor.parentRoute
+    }
+    // Update the error to point to the error handling route
+    err.routeId = routeCursor.id
+  }
+
   // Ensure a NotFoundComponent exists on the route
   if (
     !routeCursor.options.notFoundComponent &&
@@ -84,11 +93,6 @@ const _handleNotFound = (inner: InnerLoadContext, err: NotFoundError) => {
     error: err,
     isFetching: false,
   }))
-
-  if ((err as any).routerCode === 'BEFORE_LOAD' && routeCursor.parentRoute) {
-    err.routeId = routeCursor.parentRoute.id
-    _handleNotFound(inner, err)
-  }
 }
 
 const handleRedirectAndNotFound = (

packages/router-core/src/ssr/ssr-client.ts

@@ -210,7 +210,9 @@ export async function hydrate(router: AnyRouter): Promise<any> {
       match.styles = headFnContent?.styles
       match.scripts = scripts
     }),
-  )
+  ).catch((err) => {
+    console.error('Error during route context hydration:', err)
+  })
 
   const isSpaMode = matches[matches.length - 1]!.id !== lastMatchId
   const hasSsrFalseMatches = matches.some((m) => m.ssr === false)