fix(router): handle unknown error boundary values

.changeset/calm-errors-listen.md

@@ -0,0 +1,8 @@
+---
+'@tanstack/react-router': patch
+'@tanstack/router-core': patch
+'@tanstack/solid-router': patch
+'@tanstack/vue-router': patch
+---
+
+Handle arbitrary thrown values in router error boundaries and type caught errors as `unknown`.

docs/router/api/router/RouterOptionsType.md

@@ -141,7 +141,7 @@ The `RouterOptions` type accepts an object with the following properties and met
 
 ### `defaultOnCatch` property
 
-- Type: `(error: Error, errorInfo: ErrorInfo) => void`
+- Type: `(error: unknown, errorInfo: ErrorInfo) => void`
 - Optional
 - The default `onCatch` handler for errors caught by the Router ErrorBoundary
 

docs/router/guide/data-loading.md

@@ -570,7 +570,7 @@ The `routeOptions.onCatch` option is a function that is called whenever an error
 ```tsx
 // src/routes/posts.tsx
 export const Route = createFileRoute('/posts')({
-  onCatch: ({ error, errorInfo }) => {
+  onCatch: (error) => {
     // Log the error
     console.error(error)
   },
@@ -581,7 +581,7 @@ export const Route = createFileRoute('/posts')({
 
 The `routeOptions.errorComponent` option is a component that is rendered when an error occurs during the route loading or rendering lifecycle. It is rendered with the following props:
 
-- `error` - The error that occurred
+- `error` - The unknown value that was thrown
 - `reset` - A function to reset the internal `CatchBoundary`
 
 ```tsx
@@ -590,7 +590,7 @@ export const Route = createFileRoute('/posts')({
   loader: () => fetchPosts(),
   errorComponent: ({ error }) => {
     // Render an error message
-    return <div>{error.message}</div>
+    return <div>{error instanceof Error ? error.message : String(error)}</div>
   },
 })
 ```
@@ -604,7 +604,7 @@ export const Route = createFileRoute('/posts')({
   errorComponent: ({ error, reset }) => {
     return (
       <div>
-        {error.message}
+        {error instanceof Error ? error.message : String(error)}
         <button
           onClick={() => {
             // Reset the router error boundary
@@ -630,7 +630,7 @@ export const Route = createFileRoute('/posts')({
 
     return (
       <div>
-        {error.message}
+        {error instanceof Error ? error.message : String(error)}
         <button
           onClick={() => {
             // Invalidate the route to reload the loader, which will also reset the error boundary

packages/react-router/src/CatchBoundary.tsx

@@ -9,29 +9,30 @@ export class CatchBoundary extends React.Component<{
   getResetKey: () => unknown
   children: React.ReactNode
   errorComponent?: ErrorRouteComponent
-  onCatch?: (error: Error, errorInfo: ErrorInfo) => void
+  onCatch?: (error: unknown, errorInfo: ErrorInfo) => void
 }> {
-  state = { error: null } as { error: Error | null; resetKey?: unknown }
+  // Wrapping caught values keeps every possible thrown value truthy.
+  state = { error: 0 } as { error: [unknown] | 0; resetKey?: unknown }
 
   static getDerivedStateFromProps(
     props: { getResetKey: () => unknown },
-    state: { resetKey?: unknown; error: Error | null },
+    state: { resetKey?: unknown; error: [unknown] | 0 },
   ) {
     const resetKey = props.getResetKey()
 
     if (state.error && state.resetKey !== resetKey) {
-      return { resetKey, error: null }
+      return { resetKey, error: 0 }
     }
 
     return { resetKey }
   }
-  static getDerivedStateFromError(error: Error) {
-    return { error }
+  static getDerivedStateFromError(error: unknown) {
+    return { error: [error] }
   }
   reset = () => {
-    this.setState({ error: null })
+    this.setState({ error: 0 })
   }
-  componentDidCatch(error: Error, errorInfo: ErrorInfo) {
+  componentDidCatch(error: unknown, errorInfo: ErrorInfo) {
     this.props.onCatch?.(error, errorInfo)
   }
   render() {
@@ -40,7 +41,7 @@ export class CatchBoundary extends React.Component<{
       const element = React.createElement(
         this.props.errorComponent ?? ErrorComponent,
         {
-          error,
+          error: error[0],
           reset: this.reset,
         },
       )
@@ -54,7 +55,7 @@ export class CatchBoundary extends React.Component<{
   }
 }
 
-export function ErrorComponent({ error }: { error: any }) {
+export function ErrorComponent({ error }: { error: unknown }) {
   const [show, setShow] = React.useState(process.env.NODE_ENV !== 'production')
 
   return (
@@ -88,7 +89,9 @@ export function ErrorComponent({ error }: { error: any }) {
               overflow: 'auto',
             }}
           >
-            {error.message ? <code>{error.message}</code> : null}
+            {(error as { message?: string } | null)?.message ? (
+              <code>{(error as { message: string }).message}</code>
+            ) : null}
           </pre>
         </div>
       ) : null}

packages/react-router/src/Match.tsx

@@ -236,7 +236,7 @@ export const MatchInner = React.memo(function MatchInnerImpl({
         ErrorComponent
       const errorElement = (
         <RouteErrorComponent
-          error={match.error as any}
+          error={match.error}
           reset={undefined as any}
           info={{
             componentStack: '',

packages/react-router/src/Matches.tsx

@@ -115,7 +115,7 @@ function MatchesInner() {
                   console.warn(
                     `Warning: The following error wasn't caught by any route! At the very least, consider setting an 'errorComponent' in your RootRoute!`,
                   )
-                  console.warn(`Warning: ${error.message || error.toString()}`)
+                  console.warn('Warning:', error)
                 }
               : undefined
           }

packages/react-router/src/not-found.tsx

@@ -9,7 +9,7 @@ import type { NotFoundError } from '@tanstack/router-core'
 
 export function CatchNotFound(props: {
   fallback?: (error: NotFoundError) => React.ReactElement
-  onCatch?: (error: Error, errorInfo: ErrorInfo) => void
+  onCatch?: (error: NotFoundError, errorInfo: ErrorInfo) => void
   children: React.ReactNode
 }) {
   const router = useRouter()

packages/react-router/src/router.ts

@@ -73,7 +73,7 @@ declare module '@tanstack/router-core' {
      * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaultoncatch-property)
      * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/data-loading#handling-errors-with-routeoptionsoncatch)
      */
-    defaultOnCatch?: (error: Error, errorInfo: React.ErrorInfo) => void
+    defaultOnCatch?: (error: unknown, errorInfo: React.ErrorInfo) => void
   }
 }
 

packages/react-router/tests/errorComponent.test.tsx

@@ -2,6 +2,7 @@ import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
 import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
 
 import {
+  CatchBoundary,
   HeadContent,
   Link,
   Outlet,
@@ -23,7 +24,11 @@ import {
 import type { ErrorComponentProps, RouterHistory } from '../src'
 
 function MyErrorComponent(props: ErrorComponentProps) {
-  return <div>Error: {props.error.message}</div>
+  return <div>Error: {getErrorMessage(props.error)}</div>
+}
+
+function getErrorMessage(error: unknown) {
+  return error instanceof Error ? error.message : String(error)
 }
 
 async function asyncToThrowFn() {
@@ -324,7 +329,9 @@ test('ancestor route errorComponent resets when a background child generation re
   let loaderCalls = 0
   const rootRoute = createRootRoute({
     component: Outlet,
-    errorComponent: ({ error }) => <div>Ancestor error: {error.message}</div>,
+    errorComponent: ({ error }) => (
+      <div>Ancestor error: {getErrorMessage(error)}</div>
+    ),
   })
   const childRoute = createRoute({
     getParentRoute: () => rootRoute,
@@ -422,6 +429,62 @@ test('errorComponent receives primitive errors thrown from beforeLoad', async ()
   expect(screen.queryByText('About route content')).not.toBeInTheDocument()
 })
 
+test.each([
+  ['false', false],
+  ['zero', 0],
+  ['negative zero', -0],
+  ['bigint zero', 0n],
+  ['empty string', ''],
+  ['null', null],
+  ['undefined', undefined],
+  ['NaN', NaN],
+] as const)('CatchBoundary renders falsy thrown value %s', (_, thrown) => {
+  vi.spyOn(console, 'error').mockImplementation(() => {})
+  const onCatch = vi.fn()
+
+  function ThrowFalsy(): never {
+    throw thrown
+  }
+
+  render(
+    <CatchBoundary
+      getResetKey={() => 0}
+      errorComponent={({ error }) => (
+        <div>{Object.is(error, thrown) ? 'Caught value' : 'Wrong value'}</div>
+      )}
+      onCatch={onCatch}
+    >
+      <ThrowFalsy />
+    </CatchBoundary>,
+  )
+
+  expect(screen.getByText('Caught value')).toBeInTheDocument()
+  expect(screen.queryByText('Wrong value')).not.toBeInTheDocument()
+  expect(onCatch).toHaveBeenCalledWith(thrown, expect.anything())
+})
+
+test.each([
+  ['null', null],
+  ['undefined', undefined],
+] as const)('default error UI renders thrown %s', async (_, thrown) => {
+  vi.spyOn(console, 'error').mockImplementation(() => {})
+  vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+  function ThrowFalsy(): never {
+    throw thrown
+  }
+
+  const rootRoute = createRootRoute({ component: ThrowFalsy })
+  const router = createRouter({
+    routeTree: rootRoute,
+    history: createMemoryHistory({ initialEntries: ['/'] }),
+  })
+
+  render(<RouterProvider router={router} />)
+
+  expect(await screen.findByText('Something went wrong!')).toBeInTheDocument()
+})
+
 test.each(['beforeLoad', 'loader'] as const)(
   'a Promise synchronously thrown from %s renders the route error UI',
   async (hook) => {
@@ -736,7 +799,9 @@ test('#4684: SSR renders head content when beforeLoad throws', async () => {
     component: function FailingRoute() {
       return <div>Route content</div>
     },
-    errorComponent: ({ error }) => <div>Error UI: {error.message}</div>,
+    errorComponent: ({ error }) => (
+      <div>Error UI: {getErrorMessage(error)}</div>
+    ),
   })
 
   const handler = createRequestHandler({

packages/react-router/tests/issue-4476-react-query-cancellation.test.tsx

@@ -77,7 +77,11 @@ test('#4476: pending navigation keeps the query observer mounted and its fetchQu
     },
     errorComponent: ({ error }) => {
       routeError(error)
-      return <div data-testid="page-two-error">{error.name}</div>
+      return (
+        <div data-testid="page-two-error">
+          {error instanceof Error ? error.name : String(error)}
+        </div>
+      )
     },
     component: () => {
       const { data } = pageTwoRoute.useRouteContext()

packages/react-router/tests/issue-6107-lazy-chunk-error-component.test.tsx

@@ -59,7 +59,11 @@ test('#6107: lazy chunk hover failure is non-fatal and navigation renders defaul
     defaultPreloadDelay: 0,
     defaultErrorComponent: ({ error }) => {
       defaultErrorRendered(error)
-      return <div data-testid="default-error">{error.message}</div>
+      return (
+        <div data-testid="default-error">
+          {error instanceof Error ? error.message : String(error)}
+        </div>
+      )
     },
   })
   const preloadRoute = vi.spyOn(router, 'preloadRoute')

packages/react-router/tests/issue-6371-search-default-normalization-abort.test.tsx

@@ -73,7 +73,11 @@ test('#6371: initial search defaults produce one live canonical loader', async (
     ),
     errorComponent: ({ error }) => {
       errorComponentRendered(error)
-      return <div data-testid="about-error">{error.message}</div>
+      return (
+        <div data-testid="about-error">
+          {error instanceof Error ? error.message : String(error)}
+        </div>
+      )
     },
   })
   const history = createMemoryHistory({ initialEntries: ['/about'] })

packages/react-router/tests/issue-7635-error-head-after-navigation.test.tsx

@@ -63,7 +63,11 @@ test('#7635: a parent beforeLoad error replaces the previous child title', async
     component: Outlet,
     errorComponent: ({ error }) => {
       appErrorRendered(error)
-      return <div data-testid="app-error">{error.message}</div>
+      return (
+        <div data-testid="app-error">
+          {error instanceof Error ? error.message : String(error)}
+        </div>
+      )
     },
   })
   const childRoute = createRoute({

packages/react-router/tests/issue-7638-invalidate-transition-error.test.tsx

@@ -95,7 +95,14 @@ function setup({ failVia }: { failVia: 'render' | 'loader' }) {
     history: createMemoryHistory({ initialEntries: ['/test'] }),
     defaultErrorComponent: (props: ErrorComponentProps) => {
       errorRenders++
-      return <div data-testid="error-ui">error: {props.error.message}</div>
+      return (
+        <div data-testid="error-ui">
+          error:{' '}
+          {props.error instanceof Error
+            ? props.error.message
+            : String(props.error)}
+        </div>
+      )
     },
   })
 

packages/react-router/tests/lazy/error.tsx

@@ -3,6 +3,10 @@ import { createLazyRoute } from '../../src'
 export function Route(id: string) {
   return createLazyRoute(id)({
     component: () => <div>About route content</div>,
-    errorComponent: ({ error }) => <div>Lazy Error: {error.message}</div>,
+    errorComponent: ({ error }) => (
+      <div>
+        Lazy Error: {error instanceof Error ? error.message : String(error)}
+      </div>
+    ),
   })
 }

packages/react-router/tests/loaders.test.tsx

@@ -922,7 +922,9 @@ test('reproducer for #6388 - rapid navigation between parameterized routes shoul
       errorComponentRenderCount(error)
       return (
         <div data-testid="error-component">
-          Error Component: {error.message} | Name: {error.name}
+          Error Component:{' '}
+          {error instanceof Error ? error.message : String(error)} | Name:{' '}
+          {error instanceof Error ? error.name : typeof error}
         </div>
       )
     },