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

[nlynzaad]

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

[coderabbitai]

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 name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The 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	✅ Passed	No 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.}

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 46b6819

Command	Status	Duration	Result
nx affected --targets=test:eslint,test:unit,tes...	✅ Succeeded	<1s	View ↗
nx run-many --target=build --exclude=examples/*...	✅ Succeeded	31s	View ↗

---

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

[pkg-pr-new]

More templates

• tanstack-router-solid-example-basic
• tanstack-router-solid-example-basic-devtools-panel
• tanstack-router-solid-example-basic-file-based
• tanstack-router-solid-example-basic-non-nested-devtools
• tanstack-router-solid-example-basic-solid-query
• tanstack-router-solid-example-basic-solid-query-file-based
• tanstack-router-solid-example-basic-ssr-streaming-file-based
• tanstack-router-solid-example-kitchen-sink-file-based
• tanstack-router-solid-example-quickstart-file-based
• tanstack-solid-start-example-bare
• tanstack-solid-start-example-basic
• tanstack-solid-start-example-basic-static
• tanstack-router-react-example-authenticated-routes
• tanstack-router-react-example-authenticated-routes-firebase
• tanstack-router-react-example-basic
• tanstack-router-react-example-basic-default-search-params
• tanstack-router-react-example-basic-devtools-panel
• tanstack-router-react-example-basic-file-based
• tanstack-router-react-example-basic-non-nested-devtools
• tanstack-router-react-example-react-query
• tanstack-router-react-example-basic-react-query-file-based
• tanstack-router-react-example-basic-ssr-file-based
• tanstack-router-react-example-basic-ssr-streaming-file-based
• tanstack-router-react-example-basic-virtual-file-based
• tanstack-router-react-example-basic-virtual-inside-file-based
• tanstack-router-react-example-deferred-data
• tanstack-router-i18n-paraglide
• tanstack-router-react-example-kitchen-sink
• tanstack-router-react-example-kitchen-sink-file-based
• tanstack-router-react-example-kitchen-sink-react-query
• tanstack-router-react-example-kitchen-sink-react-query-file-based
• tanstack-router-react-example-large-file-based
• tanstack-router-react-example-location-masking
• tanstack-router-react-example-navigation-blocking
• tanstack-router-react-example-quickstart
• tanstack-router-react-example-quickstart-esbuild-file-based
• tanstack-router-react-example-quickstart-file-based
• tanstack-router-react-example-quickstart-rspack-file-based
• tanstack-router-react-example-quickstart-webpack-file-based
• router-monorepo-react-query
• router-mono-simple
• router-mono-simple-lazy
• tanstack-router-react-example-scroll-restoration
• tanstack-search-validator-adapters
• tanstack-start-example-bare
• tanstack-start-example-basic
• tanstack-start-example-basic-auth
• tanstack-start-example-basic-cloudflare
• tanstack-start-example-basic-react-query
• tanstack-start-example-basic-static
• tanstack-start-bun-hosting
• tanstack-start-example-convex-trellaux
• tanstack-start-example-counter
• tanstack-start-i18n-paraglide
• tanstack-start-example-large
• tanstack-start-example-material-ui
• tanstack-start-streaming-data-from-server-functions
• tanstack-start-example-supabase-basic
• tanstack-start-tailwind-v4
• tanstack-start-example-trellaux
• tanstack-start-example-workos
• tanstack-router-react-example-view-transitions
• tanstack-router-react-example-with-framer-motion
• tanstack-router-react-example-with-trpc
• tanstack-router-react-example-with-trpc-react-query

@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

[coderabbitai]

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 163b75e and 46b6819.

📒 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.