Contain route loader and render errors

CONTRACT

Execution contract

Use when: Use when loader or render failures should be isolated to one route with a recovery action.
Avoid when: Do not use a generic errorComponent for expected not-found or redirect control flow.
Preconditions: Classify not found, redirect, retryable failure, and unknown exception, then choose the nearest recovery boundary.
Verification: Trigger loader and component failures; sibling routes stay usable, retry resets state, and unknown errors remain observable.
Failure mode: A stale error after retry usually means the request reran without resetting Router error state.
Security: User-facing errors must not expose stacks, secrets, database details, or internal response bodies.

Behavior contract

Ordinary errors thrown from loader, beforeLoad, or rendering are handled by the nearest route errorComponent. notFound and redirect have dedicated control flow and should not be converted to ordinary Error objects.

Route-level recovery

reset clears the boundary. Render stable user-facing copy and send internal details to logging. Do not render error.stack outside controlled development tooling.

src/routes/issues/index.tsxtsx

import type { ErrorComponentProps } from '@tanstack/react-router'

function IssuesError({ reset }: ErrorComponentProps) {
  return (
    <section role="alert">
      <h1>Unable to load issues.</h1>
      <button type="button" onClick={reset}>Retry</button>
    </section>
  )
}

export const Route = createFileRoute('/issues/')({
  loader: loadIssues,
  errorComponent: IssuesError,
  component: IssuesPage,
})

Global fallback

Configure defaultErrorComponent in createRouter for routes without a local boundary. A boundary is not monitoring; production still needs exception, route-location, and request-correlation logging.

PRIMARY SOURCEShttps://tanstack.com/start/latest/docs/framework/react/guide/error-boundaries