fix: handle beforeLoad throwing notFound correctly (#6811)

Author: schiller-manuel

docs/router/guide/not-found-errors.md

@@ -166,7 +166,13 @@ The not-found error above will be handled by the same route or nearest parent ro
 
 If neither the route nor any suitable parent route is found to handle the error, the root route will handle it using TanStack Router's **extremely basic (and purposefully undesirable)** default not-found component that simply renders `<p>Not Found</p>`. It's highly recommended to either attach at least one `notFoundComponent` to the root route or configure a router-wide `defaultNotFoundComponent` to handle not-found errors.
 
-> ⚠️ Throwing a notFound error in a beforeLoad method will always trigger the \_\_root notFoundComponent. Since beforeLoad methods are run prior to the route loader methods, there is no guarantee that any required data for layouts have successfully loaded before the error is thrown.
+> ⚠️ When you throw `notFound()` in `beforeLoad`, TanStack Router resolves it the same way as other not-found errors:
+>
+> - If you pass `routeId`, that route (or the nearest valid ancestor boundary) handles it.
+> - If you don't pass `routeId`, the nearest route/ancestor with a `notFoundComponent` handles it (based on the router's mode and matching rules).
+> - If no suitable boundary is found, handling falls back to the root/default not-found behavior.
+>
+> For `beforeLoad`-thrown not-found errors, TanStack Router still runs required parent loaders so the selected not-found boundary can render with the loader data it depends on.
 
 ## Specifying Which Routes Handle Not Found Errors
 

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

@@ -175,6 +175,14 @@ function RootDocument({ children }: { children: React.ReactNode }) {
           >
             redirect
           </Link>{' '}
+          <Link
+            to="/not-found"
+            activeProps={{
+              className: 'font-bold',
+            }}
+          >
+            not-found
+          </Link>{' '}
           <Link
             to="/client-only"
             activeProps={{

e2e/react-start/basic/src/routes/__root.tsx

@@ -0,0 +1,36 @@
+import { createFileRoute, notFound } from '@tanstack/react-router'
+import type { NotFoundRouteProps } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/not-found/deep/b/c/d')({
+  loaderDeps: ({ search }) => ({
+    throwAt: search.throwAt,
+  }),
+  beforeLoad: ({ search }) => {
+    if (search.throwAt === 'd') {
+      throw notFound({
+        data: { source: 'd-beforeLoad' },
+      })
+    }
+  },
+  loader: ({ deps }) => {
+    if (deps.throwAt === 'c') {
+      throw new Error('d-loader-should-not-run-when-c-beforeLoad-throws')
+    }
+    return { ready: true }
+  },
+  component: RouteComponent,
+  notFoundComponent: (props: NotFoundRouteProps) => (
+    <div data-testid="deep-d-notFound-component">
+      Not Found at /not-found/deep/b/c/d (
+      {(props.data as { source?: string })?.source ?? 'unknown'})
+    </div>
+  ),
+})
+
+function RouteComponent() {
+  return (
+    <div data-testid="deep-d-route-component">
+      Hello "/not-found/deep/b/c/d"!
+    </div>
+  )
+}

e2e/react-start/basic/src/routes/not-found/deep/b/c/d.tsx

@@ -0,0 +1,19 @@
+import { Outlet, createFileRoute, notFound } from '@tanstack/react-router'
+import type { NotFoundRouteProps } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/not-found/deep/b/c')({
+  beforeLoad: ({ search }) => {
+    if (search.throwAt === 'c') {
+      throw notFound({
+        data: { source: 'c-beforeLoad' },
+      })
+    }
+  },
+  component: () => <Outlet />,
+  notFoundComponent: (props: NotFoundRouteProps) => (
+    <div data-testid="deep-c-notFound-component">
+      Not Found at /not-found/deep/b/c (
+      {(props.data as { source?: string })?.source ?? 'unknown'})
+    </div>
+  ),
+})

e2e/react-start/basic/src/routes/not-found/deep/b/c/route.tsx

@@ -0,0 +1,19 @@
+import { Outlet, createFileRoute, notFound } from '@tanstack/react-router'
+import type { NotFoundRouteProps } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/not-found/deep/b')({
+  beforeLoad: ({ search }) => {
+    if (search.throwAt === 'b') {
+      throw notFound({
+        data: { source: 'b-beforeLoad' },
+      })
+    }
+  },
+  component: () => <Outlet />,
+  notFoundComponent: (props: NotFoundRouteProps) => (
+    <div data-testid="deep-b-notFound-component">
+      Not Found at /not-found/deep/b (
+      {(props.data as { source?: string })?.source ?? 'unknown'})
+    </div>
+  ),
+})

e2e/react-start/basic/src/routes/not-found/deep/b/route.tsx

@@ -0,0 +1,42 @@
+import { Link, createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/not-found/deep/')({
+  component: RouteComponent,
+})
+
+function RouteComponent() {
+  return (
+    <div>
+      <div className="mb-2">
+        <Link
+          from={Route.fullPath}
+          to="./b/c/d"
+          search={{ throwAt: 'd' }}
+          data-testid="deep-throwAt-d"
+        >
+          /not-found/deep/b/c/d?throwAt=d
+        </Link>
+      </div>
+      <div className="mb-2">
+        <Link
+          from={Route.fullPath}
+          to="./b/c/d"
+          search={{ throwAt: 'c' }}
+          data-testid="deep-throwAt-c"
+        >
+          /not-found/deep/b/c/d?throwAt=c
+        </Link>
+      </div>
+      <div className="mb-2">
+        <Link
+          from={Route.fullPath}
+          to="./b/c/d"
+          search={{ throwAt: 'b' }}
+          data-testid="deep-throwAt-b"
+        >
+          /not-found/deep/b/c/d?throwAt=b
+        </Link>
+      </div>
+    </div>
+  )
+}

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

@@ -0,0 +1,9 @@
+import { Outlet, createFileRoute } from '@tanstack/react-router'
+import z from 'zod'
+
+export const Route = createFileRoute('/not-found/deep')({
+  validateSearch: z.object({
+    throwAt: z.enum(['b', 'c', 'd']).optional(),
+  }),
+  component: () => <Outlet />,
+})

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

@@ -25,6 +25,36 @@ export const Route = createFileRoute('/not-found/')({
             via-loader
           </Link>
         </div>
+        <div className="mb-2">
+          <Link
+            from={Route.fullPath}
+            to="./via-beforeLoad-target-root"
+            preload={preload}
+            data-testid="via-beforeLoad-target-root"
+          >
+            via-beforeLoad-target-root (shows global not-found)
+          </Link>
+        </div>
+        <div className="mb-2">
+          <Link
+            from={Route.fullPath}
+            to="./parent-boundary"
+            preload={preload}
+            data-testid="parent-boundary-index"
+          >
+            parent-boundary test cases
+          </Link>
+        </div>
+        <div className="mb-2">
+          <Link
+            from={Route.fullPath}
+            to="./deep"
+            preload={preload}
+            data-testid="deep-index"
+          >
+            deep test cases
+          </Link>
+        </div>
       </div>
     )
   },

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

@@ -0,0 +1,31 @@
+import { Link, createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/not-found/parent-boundary/')({
+  component: RouteComponent,
+})
+
+function RouteComponent() {
+  return (
+    <div>
+      <div className="mb-2">
+        <Link
+          from={Route.fullPath}
+          to="./via-beforeLoad"
+          data-testid="parent-boundary-via-beforeLoad-with-routeId"
+        >
+          via-beforeLoad (with routeId)
+        </Link>
+      </div>
+      <div className="mb-2">
+        <Link
+          from={Route.fullPath}
+          to="./via-beforeLoad"
+          search={{ target: 'none' }}
+          data-testid="parent-boundary-via-beforeLoad-without-routeId"
+        >
+          via-beforeLoad (without routeId)
+        </Link>
+      </div>
+    </div>
+  )
+}