Skip to content
Source
Sign inSign up
TanStack/router

docs(beforeLoad & notFoundComponents): Add note regarding notFound error thrown from beforeLoad function #5500

Mergednlynzaad(GitHub profile, opens in a new tab)merged 2 commits intomain fromrefs/pull/5500/headmerged by nlynzaad(GitHub profile, opens in a new tab)

There have been a couple of issues, see #5498, #3321, #2139, etc., raised regarding this.

As per this discussion in discord, it is not currently possible to throw notFound errors in beforeLoad methods and have the nearest notFoundComponent render as with normal loader methods; it will always return the notFoundComponent on the __root route.

This PR adds a note to the documentation regarding this behaviour.

Summary by CodeRabbit

  • Documentation

    • Updated not-found error handling guide with clearer behavior explanations and edge cases
    • Added migration path for updating route configuration
  • New Features

    • Root route now supports notFoundComponent configuration option
    1. Walkthrough

      Documentation updates migration from notFoundRoute to notFoundComponent on the root route configuration, and adds a warning about notFound behavior when thrown in beforeLoad methods.

      Changes

      Cohort / File(s)Summary
      Documentation updates
      docs/router/framework/react/guide/not-found-errors.md
      Migrates API usage from notFoundRoute to notFoundComponent option on the root route. Adds warning explaining that throwing notFound in beforeLoad methods triggers the root notFoundComponent since beforeLoad runs before layout data is loaded.

      Estimated code review effort

      🎯 1 (Trivial) | ⏱️ ~3 minutes

      Poem

      🐰 A hop through the docs, a change takes flight, notFoundComponent shines so bright! We bid farewell to notFoundRoute of old, The root route's new way—far less bold. BeforeLoad beware—the root takes the call! 🌟

      Pre-merge checks and finishing touches

      ✅ Passed checks (3 passed)
      Check nameStatusExplanation
      Description Check✅ PassedCheck skipped - CodeRabbit’s high-level summary is enabled.
      Title Check✅ PassedThe PR title "docs(beforeLoad & notFoundComponents): Add note regarding notFound error thrown from beforeLoad function" is directly and fully related to the main change described in the pull request objectives. The title clearly captures the primary documentation update: adding a note explaining that throwing notFound errors from beforeLoad functions will always trigger the root notFoundComponent rather than the nearest route's notFoundComponent. The title is concise, specific, and uses conventional formatting that makes the intent immediately clear. A teammate scanning the git history would understand that this PR documents an important behavioral distinction regarding error handling in beforeLoad methods.
      Docstring Coverage✅ PassedNo functions found in the changes. Docstring coverage check skipped.
      ✨ Finishing touches
      🧪 Generate unit tests (beta)
      • Create PR with unit tests
      • Post copyable unit tests in a comment
      • Commit unit tests in branch `docs-beforeLoad-notFound-error`

      Comment `@coderabbitai help` to get the list of available commands and usage tips.
    2. View your CI Pipeline Execution ↗ for commit 46b6819b0ced77d77a7c771e7d08d1971027954a

      CommandStatusDurationResult
      nx affected --targets=test:eslint,test:unit,tes...✅ Succeeded<1sView ↗
      nx run-many --target=build --exclude=examples/*...✅ Succeeded31sView ↗

      ☁️ Nx Cloud last updated this comment at 2025-10-16 20:22:30 UTC

    3. More templates

      @tanstack/arktype-adapter

      npm i https://pkg.pr.new/TanStack/router/@tanstack/arktype-adapter@5500

      @tanstack/directive-functions-plugin

      npm i https://pkg.pr.new/TanStack/router/@tanstack/directive-functions-plugin@5500

      @tanstack/eslint-plugin-router

      npm i https://pkg.pr.new/TanStack/router/@tanstack/eslint-plugin-router@5500

      @tanstack/history

      npm i https://pkg.pr.new/TanStack/router/@tanstack/history@5500

      @tanstack/nitro-v2-vite-plugin

      npm i https://pkg.pr.new/TanStack/router/@tanstack/nitro-v2-vite-plugin@5500

      @tanstack/react-router

      npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router@5500

      @tanstack/react-router-devtools

      npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router-devtools@5500

      @tanstack/react-router-ssr-query

      npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router-ssr-query@5500

      @tanstack/react-start

      npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start@5500

      @tanstack/react-start-client

      npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-client@5500

      @tanstack/react-start-server

      npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-server@5500

      @tanstack/router-cli

      npm i https://pkg.pr.new/TanStack/router/@tanstack/router-cli@5500

      @tanstack/router-core

      npm i https://pkg.pr.new/TanStack/router/@tanstack/router-core@5500

      @tanstack/router-devtools

      npm i https://pkg.pr.new/TanStack/router/@tanstack/router-devtools@5500

      @tanstack/router-devtools-core

      npm i https://pkg.pr.new/TanStack/router/@tanstack/router-devtools-core@5500

      @tanstack/router-generator

      npm i https://pkg.pr.new/TanStack/router/@tanstack/router-generator@5500

      @tanstack/router-plugin

      npm i https://pkg.pr.new/TanStack/router/@tanstack/router-plugin@5500

      @tanstack/router-ssr-query-core

      npm i https://pkg.pr.new/TanStack/router/@tanstack/router-ssr-query-core@5500

      @tanstack/router-utils

      npm i https://pkg.pr.new/TanStack/router/@tanstack/router-utils@5500

      @tanstack/router-vite-plugin

      npm i https://pkg.pr.new/TanStack/router/@tanstack/router-vite-plugin@5500

      @tanstack/server-functions-plugin

      npm i https://pkg.pr.new/TanStack/router/@tanstack/server-functions-plugin@5500

      @tanstack/solid-router

      npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router@5500

      @tanstack/solid-router-devtools

      npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router-devtools@5500

      @tanstack/solid-start

      npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start@5500

      @tanstack/solid-start-client

      npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-client@5500

      @tanstack/solid-start-server

      npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-server@5500

      @tanstack/start-client-core

      npm i https://pkg.pr.new/TanStack/router/@tanstack/start-client-core@5500

      @tanstack/start-plugin-core

      npm i https://pkg.pr.new/TanStack/router/@tanstack/start-plugin-core@5500

      @tanstack/start-server-core

      npm i https://pkg.pr.new/TanStack/router/@tanstack/start-server-core@5500

      @tanstack/start-static-server-functions

      npm i https://pkg.pr.new/TanStack/router/@tanstack/start-static-server-functions@5500

      @tanstack/start-storage-context

      npm i https://pkg.pr.new/TanStack/router/@tanstack/start-storage-context@5500

      @tanstack/valibot-adapter

      npm i https://pkg.pr.new/TanStack/router/@tanstack/valibot-adapter@5500

      @tanstack/virtual-file-routes

      npm i https://pkg.pr.new/TanStack/router/@tanstack/virtual-file-routes@5500

      @tanstack/zod-adapter

      npm i https://pkg.pr.new/TanStack/router/@tanstack/zod-adapter@5500

      commit: 46b6819

    4. Actionable comments posted: 0

      🧹 Nitpick comments (1)
      docs/router/framework/react/guide/not-found-errors.md (1)

      169-170: Simplify wording in the beforeLoad warning.

      The warning clearly explains the beforeLoad limitation, but "prior to" is verbose and can be simplified. Consider using "before" instead for brevity.

      -> ⚠️ Throwing a notFound error in a beforeLoad method will always trigger the \_\_root notFoundComponent. Since beforeLoad methods are run before the route loader methods, there is no guarantee that any required data for layouts have successfully loaded before the error is thrown.
      📜 Review details

      Configuration used: CodeRabbit UI

      Review profile: CHILL

      Plan: Pro

      📥 Commits

      Reviewing files that changed from the base of the PR and between 163b75e38416de733430ef48aa8ef0f29b4e8bcc and 46b6819b0ced77d77a7c771e7d08d1971027954a.

      📒 Files selected for processing (1)
      • docs/router/framework/react/guide/not-found-errors.md (1 hunks)
      🧰 Additional context used
      📓 Path-based instructions (2)
      docs/**/*.{md,mdx}

      📄 CodeRabbit inference engine (AGENTS.md)

      Use internal docs links relative to the docs/ folder (e.g., ./guide/data-loading)

      Files:

      • docs/router/framework/react/guide/not-found-errors.md
      docs/{router,start}/**

      📄 CodeRabbit inference engine (AGENTS.md)

      Place router docs under docs/router/ and start framework docs under docs/start/

      Files:

      • docs/router/framework/react/guide/not-found-errors.md
      🪛 LanguageTool
      docs/router/framework/react/guide/not-found-errors.md

      [style] ~169-~169: ‘prior to’ might be wordy. Consider a shorter alternative. Context: ...onent. Since beforeLoad methods are run prior to the route loader methods, there is no g...

      (EN_WORDINESS_PREMIUM_PRIOR_TO)

      🔇 Additional comments (1)
      docs/router/framework/react/guide/not-found-errors.md (1)

      261-261: Update documentation link format per coding guidelines.

      The current link ../ssr.md uses relative path traversal. Per coding guidelines, internal docs links should be relative to the docs/ folder (e.g., ./guide/data-loading). This file is located at docs/router/framework/react/guide/not-found-errors.md, so the link should reference the SSR documentation appropriately.

      Verify the correct path and update the link format:

      -See [SSR guide](../ssr.md) for more information.
      +See [SSR guide](../ssr) for more information.

Sign in to join this conversation.