Postconditions: what we check

• useNavigate · invalid-route-path

  warning
  WhenNavigation target route does not exist
  ThrowsError indicating route not found
  Required handlingCaller SHOULD handle navigation errors with error boundary or try-catch if using navigate programmatically. Invalid routes will throw at runtime. TypeScript type checking enforces valid route paths at compile time — TypeScript users with strict route types satisfy this requirement statically.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• useNavigate · navigation-during-unmount

  warning
  WhenNavigation is triggered after component unmounts
  ThrowsError indicating component is unmounted
  Required handlingCaller MUST either cleanup navigation side effects or use error boundary to catch unmount errors. Common in async navigation (e.g., after API call completes).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• useNavigate · invalid-params

  error
  WhenNavigation params do not match route's param types
  ThrowsError indicating invalid params for target route
  Required handlingCaller MUST ensure params match the target route's expected types. TypeScript types help but runtime validation still needed.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• useMatch · route-mismatch-strict

  error
  WhenCurrent route doesn't match 'from' parameter when strict: true
  ThrowsError indicating route mismatch
  Required handlingCaller MUST either use correct 'from' route, set strict: false for shared components, or wrap in error boundary to handle mismatch gracefully.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• useMatch · route-not-found

  error
  WhenRoute specified in 'from' parameter does not exist
  ThrowsError indicating route not found
  Required handlingCaller MUST ensure route exists before calling useMatch with that route. Verify route is registered in router configuration.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4]
• useLoaderData · loader-error-unhandled

  error
  WhenRoute loader throws an error during data loading
  ThrowsError from loader function
  Required handlingCaller MUST implement ErrorComponent in route definition or parent route to catch loader errors. Without error boundary, loader errors crash the app.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5]
• useLoaderData · loader-data-unavailable

  error
  WhenLoader data is accessed before loader completes
  ThrowsError indicating data not yet loaded
  Required handlingCaller MUST handle Suspense boundaries properly. useLoaderData throws when data is not yet available, triggering Suspense.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6]
• useLoaderData · no-loader-defined

  error
  WhenuseLoaderData called on route without loader function
  ThrowsError indicating no loader defined for route
  Required handlingCaller MUST ensure route has loader function defined before calling useLoaderData. Check route configuration.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6]
• useParams · param-type-mismatch

  warning
  WhenActual param value doesn't match expected type from route definition
  ThrowsError indicating type mismatch
  Required handlingCaller SHOULD validate params match expected types. TanStack Router v1 with strict TypeScript types validates params at compile time. Runtime validation adds defense-in-depth but may not be required when TypeScript enforces the type contract.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• useParams · required-param-missing

  error
  WhenRequired route param is missing or undefined
  ThrowsError indicating required param missing
  Required handlingCaller MUST ensure all required params are provided when navigating to route. Check route configuration for required params.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• useSearch · search-schema-validation-error

  warning
  WhenSearch params don't match route's search schema validation
  ThrowsError with validation details
  Required handlingCaller SHOULD handle search param validation errors with error boundary. Use validateSearch option in route to define validation schema. When validateSearch uses a Zod schema, the validation itself satisfies this requirement — the schema ensures params are validated before use.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6]
• useSearch · search-param-parse-error

  error
  WhenSearch param value cannot be parsed to expected type
  ThrowsError indicating parse failure
  Required handlingCaller MUST validate search param types. URL strings may not match expected types (e.g., number, boolean, array).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6]
• useRouteContext · context-not-available

  error
  WhenRoute context accessed before route provides context
  ThrowsError indicating context not available
  Required handlingCaller MUST ensure route or parent route provides context via beforeLoad or context option. Wrap in error boundary or provide fallback.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[7]
• useRouteContext · route-mismatch-strict-context

  error
  WhenCurrent route doesn't match 'from' parameter when strict: true
  ThrowsError indicating route mismatch
  Required handlingCaller MUST use correct 'from' route or set strict: false for shared components.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• createRouter · duplicate-route-paths

  error
  WhenMultiple routes defined with same path
  ThrowsError indicating duplicate route path
  Required handlingCaller MUST ensure all route paths are unique within router configuration. Check for conflicting route definitions.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[8]
• createRouter · invalid-route-hierarchy

  error
  WhenRoute hierarchy is invalid (e.g., child route without parent)
  ThrowsError indicating invalid route tree
  Required handlingCaller MUST ensure route hierarchy is valid with proper parent-child relationships. Wrap createRouter in try-catch during initialization.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[8]
• createRouter · missing-root-route

  error
  WhenRouter configuration missing root route
  ThrowsError indicating no root route defined
  Required handlingCaller MUST provide root route using createRootRoute or createRootRouteWithContext.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[8]
• Navigate · invalid-route-navigate

  error
  WhenNavigate component targets non-existent route
  ThrowsError indicating route not found
  Required handlingCaller MUST ensure target route exists before rendering Navigate component. Wrap in error boundary to prevent crashes.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4]
• Navigate · navigate-infinite-loop

  error
  WhenNavigate component causes infinite navigation loop
  ThrowsError indicating max navigation depth exceeded
  Required handlingCaller MUST avoid navigation loops by checking conditions before rendering Navigate. Use replace prop to prevent history stack overflow.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• Link · invalid-route-link

  error
  WhenLink component targets non-existent route
  ThrowsError indicating route not found
  Required handlingCaller MUST ensure target route exists. Invalid links throw at render time. Use error boundary to catch link errors.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• Link · invalid-link-params

  error
  WhenLink params don't match target route's param types
  ThrowsError indicating invalid params
  Required handlingCaller MUST ensure link params match target route's expected types. TypeScript helps but runtime validation needed.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• createRoute · invalid-loader-function

  error
  WhenLoader function throws during route initialization
  ThrowsError from loader function
  Required handlingCaller MUST ensure loader function is defined correctly and doesn't throw during initialization. Wrap route definition in try-catch if loader has initialization logic.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6]
• createRoute · invalid-search-schema

  error
  WhenSearch validation schema is invalid or malformed
  ThrowsError indicating invalid schema
  Required handlingCaller MUST ensure validateSearch function is correctly defined and returns valid schema. Test schema validation during development.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6]
• useBlocker · blocker-shouldblock-fn-uncaught-rejection

  error
  WhenshouldBlockFn is async and its returned Promise rejects (network call or other async operation fails inside shouldBlockFn)
  Required handlingCaller MUST wrap shouldBlockFn body in try-catch and resolve to a boolean even on error. Do not let shouldBlockFn reject — catch errors internally and return false (allow navigation) or true (block) as a safe default.
  costhighin prodsilent failureusers seelost datavisibilitysilent
  Sources[9]
• useBlocker · blocker-external-navigation-bypass

  warning
  WhenMultiple navigation blockers registered and one throws an error before others can run
  Required handlingCaller SHOULD ensure only one navigation blocker is active per component to avoid ordering dependencies. Defensive shouldBlockFn implementations should never throw.
  costmediumin prodsilent failureusers seelost datavisibilitysilent
  Sources[10]
• useAwaited · awaited-deferred-rejection-no-error-boundary

  error
  WhenDeferred Promise passed to useAwaited rejects and no error boundary wraps the component
  Required handlingCaller MUST wrap useAwaited/Await usage in either: (1) a route errorComponent defined on the route that passes loader data, (2) a React Suspense + ErrorBoundary pair, or (3) the CatchBoundary component from @tanstack/react-router. Without an error boundary, deferred data loading failures crash the UI.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[11]
• useAwaited · awaited-missing-suspense-boundary

  error
  WhenuseAwaited called with a pending deferred promise and no React Suspense boundary in the ancestor tree
  Required handlingCaller MUST either: (1) use Await with a fallback prop to auto-wrap in Suspense, (2) wrap useAwaited calls in a React.Suspense boundary, or (3) use within a route that has pendingComponent defined. Every deferred data access point needs a Suspense boundary.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[11]
• lazyRouteComponent · lazy-route-component-import-failure

  error
  WhenDynamic import fails due to network error, wrong path, or non-ModuleNotFound error
  Required handlingCaller MUST define an errorComponent on the route that uses lazyRouteComponent, or wrap the route in a CatchBoundary. Without an error boundary, import failures permanently crash the route subtree. Additionally, the parent route should define errorComponent to catch lazy load failures during navigation.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[12][13]
• lazyRouteComponent · lazy-route-component-chunk-hash-mismatch-loop

  warning
  WhenChunk hash mismatch after new deploy: single auto-reload fires but module still not found (CDN cache serving old assets)
  Required handlingCaller SHOULD implement errorComponent on routes using lazy components to display a user-friendly "Please refresh the page" message when the auto-reload cannot resolve the chunk. This catches the post-reload throw loop.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[12]
• useLoaderDeps · loader-deps-route-mismatch-strict

  error
  Whenstrict: true (default) and current route does not match the 'from' parameter
  Required handlingCaller MUST either: (1) use the correct 'from' route ID matching the current route, (2) set strict: false when using in shared components rendered across multiple routes, or (3) wrap in error boundary. TypeScript strict route types catch most cases at compile time when using file-based routing.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[14][3]
• RouterProvider · router-provider-loader-initialization-error

  error
  WhenRoot route loader or beforeLoad hook throws a non-redirect, non-notFound error during app initialization
  Required handlingCaller MUST define errorComponent on the root route or wrap RouterProvider in a top-level React ErrorBoundary to catch initialization failures. Root-level loaders (e.g., auth checks in beforeLoad) that throw will crash the app if no error boundary exists at or above RouterProvider.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[15][16]
• RouterProvider · router-provider-missing-context

  error
  WhenAny TanStack Router hook used outside RouterProvider component tree (context returns null)
  Required handlingCaller MUST ensure all TanStack Router hooks are used within a component tree that has RouterProvider as an ancestor. For components used in both router and non-router contexts (e.g., Storybook), wrap hook usage in conditional checks or use useRouter({ warn: false }) and check for null before calling methods.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[17]

Sources

Every postcondition cites at least one of these. Grouped by source type; numbered to match the footnotes above.

Research notes

Curator notes from SOURCES.md captured when the profile was written so you can verify the reasoning, not just the rules.