fix(router-core): model error component props as unknown

.changeset/error-component-props-unknown.md

@@ -0,0 +1,30 @@
+---
+'@tanstack/router-core': minor
+'@tanstack/react-router': minor
+'@tanstack/solid-router': minor
+'@tanstack/vue-router': minor
+---
+
+Type the `error` prop passed to error components as `unknown` instead of `Error`.
+
+Route loading and rendering code can throw any value — a primitive, a rich
+domain object, or an `Error` — and the router already modelled `RouteMatch.error`
+as `unknown`. Only the error-component contract claimed `Error`, which forced an
+`as any` cast internally and misled consumers into unguarded `error.message`
+access that could fail at runtime.
+
+`ErrorComponentProps` no longer takes a `TError` type parameter. The parameter
+was introduced in a previous release but never propagated through route
+configuration or the React, Solid, and Vue `ErrorRouteComponent` contracts, so
+it could not describe the thrown value. A typed-error API can be revisited if an
+explicit error type can be threaded end to end.
+
+Error components must now narrow before accessing error-specific properties:
+
+```tsx
+errorComponent: ({ error }) => {
+  const message = error instanceof Error ? error.message : String(error)
+
+  return <div>{message}</div>
+}
+```

docs/router/api/router/errorComponentComponent.md

@@ -11,9 +11,22 @@ The `ErrorComponent` component accepts the following props:
 
 ### `props.error` prop
 
-- Type: `TError` (defaults to `Error`)
+- Type: `unknown`
 - The error that was thrown by the component's children
 
+  Anything can be thrown in JavaScript, and route loading and rendering code is
+  no exception — a `loader` may `throw 'oops'` or throw a rich domain object
+  instead of an `Error`. The prop is therefore typed as `unknown`, and error
+  components must narrow the value before accessing error-specific properties:
+
+  ```tsx
+  errorComponent: ({ error }) => {
+    const message = error instanceof Error ? error.message : String(error)
+
+    return <div>{message}</div>
+  }
+  ```
+
 ### `props.info` prop
 
 - Type: `{ componentStack: string }`

docs/router/guide/data-loading.md

@@ -559,16 +559,16 @@ 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 error that occurred, typed as `unknown`. Anything can be thrown, so narrow it before accessing error-specific properties.
 - `reset` - A function to reset the internal `CatchBoundary`
 
 ```tsx
 // src/routes/posts.tsx
 export const Route = createFileRoute('/posts')({
   loader: () => fetchPosts(),
   errorComponent: ({ error }) => {
-    // Render an error message
-    return <div>{error.message}</div>
+    // `error` is `unknown`, so narrow it before reading `message`
+    return <div>{error instanceof Error ? error.message : String(error)}</div>
   },
 })
 ```
@@ -582,7 +582,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
@@ -608,7 +608,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

docs/router/guide/external-data-loading.md

@@ -118,7 +118,7 @@ export const Route = createFileRoute('/')({
 
     return (
       <div>
-        {error.message}
+        {error instanceof Error ? error.message : String(error)}
         <button
           onClick={() => {
             // Invalidate the route to reload the loader, and reset any router error boundaries

docs/router/how-to/setup-testing.md

@@ -224,8 +224,12 @@ export function LoadingComponent() {
   return <div data-testid="loading">Loading...</div>
 }
 
-export function ErrorComponent({ error }: { error: Error }) {
-  return <div data-testid="error">Error: {error.message}</div>
+export function ErrorComponent({ error }: { error: unknown }) {
+  return (
+    <div data-testid="error">
+      Error: {error instanceof Error ? error.message : String(error)}
+    </div>
+  )
 }
 ```
 
@@ -586,8 +590,12 @@ describe('Code-Based Route Data Loading', () => {
       return <div>{user.name}</div>
     }
 
-    function ErrorComponent({ error }: { error: Error }) {
-      return <div data-testid="error">Error: {error.message}</div>
+    function ErrorComponent({ error }: { error: unknown }) {
+      return (
+        <div data-testid="error">
+          Error: {error instanceof Error ? error.message : String(error)}
+        </div>
+      )
     }
 
     const userRoute = createRoute({

docs/router/how-to/use-environment-variables.md

@@ -163,9 +163,11 @@ const fetchPosts = async () => {
 
 export const Route = createFileRoute('/posts/')({
   loader: fetchPosts,
-  errorComponent: ({ error }) => (
-    <div>Error loading posts: {error.message}</div>
-  ),
+  errorComponent: ({ error }) => {
+    const message = error instanceof Error ? error.message : String(error)
+
+    return <div>Error loading posts: {message}</div>
+  },
 })
 ```
 

docs/router/how-to/validate-search-params.md

@@ -36,7 +36,7 @@ export const Route = createFileRoute('/products')({
     return (
       <div className="error">
         <h2>Invalid Search Parameters</h2>
-        <p>{error.message}</p>
+        <p>{error instanceof Error ? error.message : String(error)}</p>
         <button
           onClick={() => router.navigate({ to: '/products', search: {} })}
         >
@@ -302,7 +302,7 @@ export const Route = createFileRoute('/search')({
     return (
       <div className="error">
         <h2>Invalid Search Parameters</h2>
-        <p>{error.message}</p>
+        <p>{error instanceof Error ? error.message : String(error)}</p>
         <button onClick={() => router.navigate({ to: '/search', search: {} })}>
           Reset Search
         </button>

docs/start/framework/react/guide/server-components.md

@@ -943,7 +943,11 @@ export const Route = createFileRoute('/')({
     // If this fails, the errorComponent renders
     Greeting: await getGreeting(),
   }),
-  errorComponent: ({ error }) => <div>Failed to load: {error.message}</div>,
+  errorComponent: ({ error }) => (
+    <div>
+      Failed to load: {error instanceof Error ? error.message : String(error)}
+    </div>
+  ),
   component: HomePage,
 })
 ```

packages/react-router/src/Match.tsx

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

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

@@ -0,0 +1,21 @@
+import { expectTypeOf, test } from 'vitest'
+import type { ErrorComponentProps } from '../src'
+
+test('error prop is unknown', () => {
+  expectTypeOf<ErrorComponentProps['error']>().toBeUnknown()
+})
+
+test('error-specific properties are accessible after narrowing', () => {
+  const narrowed = (props: ErrorComponentProps) =>
+    props.error instanceof Error ? props.error.message : String(props.error)
+
+  expectTypeOf(narrowed).returns.toEqualTypeOf<string>()
+})
+
+test('error-specific properties are inaccessible without narrowing', () => {
+  const unnarrowed = (props: ErrorComponentProps) =>
+    // @ts-expect-error - `error` is `unknown`; narrow it before accessing `message`
+    props.error.message
+
+  expectTypeOf(unnarrowed).toBeFunction()
+})

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

@@ -23,7 +23,10 @@ import {
 import type { ErrorComponentProps, RouterHistory } from '../src'
 
 function MyErrorComponent(props: ErrorComponentProps) {
-  return <div>Error: {props.error.message}</div>
+  const message =
+    props.error instanceof Error ? props.error.message : String(props.error)
+
+  return <div>Error: {message}</div>
 }
 
 async function asyncToThrowFn() {
@@ -380,7 +383,11 @@ 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: {error instanceof Error ? error.message : String(error)}
+      </div>
+    ),
   })
 
   const handler = createRequestHandler({

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

@@ -95,7 +95,10 @@ 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>
+      const message =
+        props.error instanceof Error ? props.error.message : String(props.error)
+
+      return <div data-testid="error-ui">error: {message}</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

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

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

@@ -1853,7 +1853,7 @@ describe('search params in URL', () => {
 
     describe.each(testCases)('search param validation', (validateSearch) => {
       it('does not throw an error when the search param is valid', async () => {
-        let errorSpy: Error | undefined
+        let errorSpy: unknown
         const rootRoute = createRootRoute({
           validateSearch,
           errorComponent: ({ error }) => {
@@ -1873,7 +1873,7 @@ describe('search params in URL', () => {
       })
 
       it('throws an error when the search param is not valid', async () => {
-        let errorSpy: Error | undefined
+        let errorSpy: unknown
         const rootRoute = createRootRoute({
           validateSearch,
           errorComponent: ({ error }) => {
@@ -1888,7 +1888,9 @@ describe('search params in URL', () => {
         await act(() => router.load())
 
         expect(errorSpy).toBeInstanceOf(SearchParamError)
-        expect(errorSpy?.cause).toBeInstanceOf(TestValidationError)
+        expect((errorSpy as SearchParamError).cause).toBeInstanceOf(
+          TestValidationError,
+        )
       })
     })
   })

packages/router-core/src/route.ts

@@ -1607,8 +1607,8 @@ export type ErrorRouteProps = {
   reset: () => void
 }
 
-export type ErrorComponentProps<TError = Error> = {
-  error: TError
+export type ErrorComponentProps = {
+  error: unknown
   info?: { componentStack: string }
   reset: () => void
 }

packages/solid-router/tests/errorComponent.test-d.tsx

@@ -0,0 +1,21 @@
+import { expectTypeOf, test } from 'vitest'
+import type { ErrorComponentProps } from '../src'
+
+test('error prop is unknown', () => {
+  expectTypeOf<ErrorComponentProps['error']>().toBeUnknown()
+})
+
+test('error-specific properties are accessible after narrowing', () => {
+  const narrowed = (props: ErrorComponentProps) =>
+    props.error instanceof Error ? props.error.message : String(props.error)
+
+  expectTypeOf(narrowed).returns.toEqualTypeOf<string>()
+})
+
+test('error-specific properties are inaccessible without narrowing', () => {
+  const unnarrowed = (props: ErrorComponentProps) =>
+    // @ts-expect-error - `error` is `unknown`; narrow it before accessing `message`
+    props.error.message
+
+  expectTypeOf(unnarrowed).toBeFunction()
+})

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

@@ -12,7 +12,10 @@ import {
 import type { ErrorComponentProps } from '../src'
 
 function MyErrorComponent(props: ErrorComponentProps) {
-  return <div>Error: {props.error.message}</div>
+  const message = () =>
+    props.error instanceof Error ? props.error.message : String(props.error)
+
+  return <div>Error: {message()}</div>
 }
 
 async function asyncToThrowFn() {

packages/solid-router/tests/link.test.tsx

@@ -3660,7 +3660,9 @@ describe('Link', () => {
 
   test('when navigating from /invoices to ./invoiceId and the current route is /posts/$postId/details', async () => {
     const rootRoute = createRootRoute({
-      errorComponent: (err) => <div>{err.error.message}</div>,
+      errorComponent: (err) => (
+        <div>{err.error instanceof Error ? err.error.message : ''}</div>
+      ),
     })
 
     const indexRoute = createRoute({
@@ -5629,7 +5631,9 @@ describe('search middleware', () => {
 
   test('search middlewares work', async () => {
     const rootRoute = createRootRoute({
-      errorComponent: (error) => <div>{error.error.stack}</div>,
+      errorComponent: (error) => (
+        <div>{error.error instanceof Error ? error.error.stack : ''}</div>
+      ),
       validateSearch: (input) => {
         return {
           root: input.root as string | undefined,