docs(beforeLoad & notFoundComponents): Add note regarding notFound error thrown from beforeLoad function #5500
main fromrefs/pull/5500/head·merged 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
notFoundComponentconfiguration option
- Root route now supports
- 1
github-actions[bot](GitHub profile, opens in a new tab) added labelsdocumentation
View your CI Pipeline Execution ↗ for commit 46b6819b0ced77d77a7c771e7d08d1971027954a
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:30UTCMore 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@5500commit:
46b6819Actionable 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.mduses 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 atdocs/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.nlynzaad(GitHub profile, opens in a new tab) closed this
Sign in to join this conversation.
Walkthrough#
Documentation updates migration from
notFoundRoutetonotFoundComponenton the root route configuration, and adds a warning about notFound behavior when thrown in beforeLoad methods.Changes#
docs/router/framework/react/guide/not-found-errors.mdnotFoundRoutetonotFoundComponentoption 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#
Pre-merge checks and finishing touches#
✅ Passed checks (3 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
Comment `@coderabbitai help` to get the list of available commands and usage tips.