fix(router-core): retain not-found boundary during navigation

[Sheraff]

Summary

• retain a successful not-found match as the terminal shared boundary during client navigation
• preserve hydrated root context while the destination is pending
• add regression coverage for root and layout-owned not-found transitions

Summary by CodeRabbit

• Bug Fixes
  • Improved navigation away from not-found pages, preserving route context during hydration.
  • Corrected not-found state handling across nested layouts and pending navigations.
  • Prevented stale not-found content from persisting when navigating to valid routes.
  • Improved loading-state behavior while route transitions are in progress.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 293202f7-3206-4659-abe2-bc3d9d168cc8

📥 Commits

Reviewing files that changed from the base of the PR and between 9f8990b and 2b710ba.

📒 Files selected for processing (3)

• packages/react-router/tests/issue-8128-context.test.tsx
• packages/react-router/tests/issue-8128-source-notfound-retention-boundary.test.tsx
• packages/router-core/src/load-client.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

The client retained-prefix logic now preserves not-found matches through their retention boundary. Regression tests cover hydrated root-level context and layout-owned fuzzy not-found navigation.

Changes

Not-found retention

Layer / File(s)	Summary
Retained-prefix boundary packages/router-core/src/load-client.ts	executeClientLane retains a not-found match before stopping. Preload matches and unsuccessful visible matches stop retention earlier.
Hydrated root not-found regression packages/react-router/tests/issue-8128-context.test.tsx	The test verifies preserved beforeLoad context, retained not-found rendering, and dashboard navigation after hydration.
Layout-owned not-found boundary regression packages/react-router/tests/issue-8128-source-notfound-retention-boundary.test.tsx	The test verifies that layout-owned not-found content clears during gated navigation and that pending and completed route content render correctly.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to 2b710

This localized navigation-boundary fix is merge-ready after normal checks and review; no actionable merge-blocking risk remains.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 2 functions across 3 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main router-core change: retaining the not-found boundary during navigation.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/retain-not-found-boundary

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 2b710ba

Command	Status	Duration	Result
nx affected --targets=test:eslint,test:unit,tes...	✅ Succeeded	13m 16s	View ↗
nx run-many --target=build --exclude=examples/*...	✅ Succeeded	2m 8s	View ↗

---

☁️ Nx Cloud last updated this comment at 2026-08-24 21:36:12 UTC

[github-actions]

🚀 Changeset Version Preview

No changeset entries found. Merging this PR will not cause a version bump for any packages.

[pkg-pr-new]

More templates

• tanstack-router-vue-example-basic-jsx
• tanstack-router-vue-example-basic-file-based-jsx
• tanstack-router-vue-example-basic-file-based-sfc
• 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-router-react-example-basic-authjs
• tanstack-start-example-basic-cloudflare
• tanstack-start-example-basic-react-query
• tanstack-start-example-basic-rsbuild
• tanstack-start-example-basic-static
• tanstack-start-bun-hosting
• tanstack-start-example-clerk-basic
• tanstack-start-example-convex-trellaux
• tanstack-start-example-counter
• tanstack-start-i18n-paraglide
• tanstack-start-example-large
• tanstack-start-example-material-ui
• tanstack-start-example-rscs
• 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-router-solid-example-authenticated-routes
• tanstack-router-solid-example-authenticated-routes-firebase
• tanstack-router-solid-example-basic
• tanstack-router-solid-example-basic-default-search-params
• 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-file-based
• tanstack-router-solid-example-basic-ssr-streaming-file-based
• tanstack-router-solid-example-basic-virtual-file-based
• tanstack-router-solid-example-basic-virtual-inside-file-based
• tanstack-router-solid-example-deferred-data
• tanstack-router-solid-i18n-paraglide
• tanstack-router-solid-example-kitchen-sink
• tanstack-router-solid-example-kitchen-sink-file-based
• tanstack-router-solid-example-kitchen-sink-solid-query
• tanstack-router-solid-example-kitchen-sink-solid-query-file-based
• tanstack-router-solid-example-large-file-based
• tanstack-router-solid-example-location-masking
• tanstack-router-solid-example-navigation-blocking
• tanstack-router-solid-example-quickstart
• tanstack-router-solid-example-quickstart-esbuild-file-based
• tanstack-router-solid-example-quickstart-file-based
• tanstack-router-solid-example-quickstart-rspack-file-based
• tanstack-router-solid-example-quickstart-webpack-file-based
• @tanstack/router-solid-mono-simple
• router-solid-mono-simple-lazy
• router-solid-monorepo-solid-query
• tanstack-router-solid-example-scroll-restoration
• tanstack-solid-router-search-validator-adapters
• tanstack-solid-start-example-basic
• tanstack-solid-start-example-basic-auth
• tanstack-solid-start-example-basic-authjs
• tanstack-solid-start-example-basic-cloudflare
• tanstack-solid-start-example-basic-netlify
• tanstack-solid-start-example-basic-nitro
• tanstack-start-example-basic-solid-query
• tanstack-solid-start-example-basic-static
• tanstack-solid-start-bun-hosting
• tanstack-solid-start-example-convex-better-auth
• tanstack-solid-start-example-counter
• tanstack-solid-start-i18n-paraglide
• tanstack-solid-start-example-large
• tanstack-solid-start-streaming-data-from-server-functions
• tanstack-solid-start-example-supabase-basic
• tanstack-solid-start-tailwind-v4
• tanstack-router-solid-example-view-transitions
• tanstack-router-solid-example-with-framer-motion
• tanstack-router-solid-example-with-trpc

@tanstack/arktype-adapter

npm i https://pkg.pr.new/@tanstack/arktype-adapter@8161

@tanstack/eslint-plugin-router

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

@tanstack/eslint-plugin-start

npm i https://pkg.pr.new/@tanstack/eslint-plugin-start@8161

@tanstack/history

npm i https://pkg.pr.new/@tanstack/history@8161

@tanstack/nitro-v2-vite-plugin

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

@tanstack/react-router

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

@tanstack/react-router-devtools

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

@tanstack/react-router-ssr-query

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

@tanstack/react-start

npm i https://pkg.pr.new/@tanstack/react-start@8161

@tanstack/react-start-client

npm i https://pkg.pr.new/@tanstack/react-start-client@8161

@tanstack/react-start-rsc

npm i https://pkg.pr.new/@tanstack/react-start-rsc@8161

@tanstack/react-start-server

npm i https://pkg.pr.new/@tanstack/react-start-server@8161

@tanstack/router-cli

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

@tanstack/router-core

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

@tanstack/router-devtools

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

@tanstack/router-devtools-core

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

@tanstack/router-generator

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

@tanstack/router-plugin

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

@tanstack/router-ssr-query-core

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

@tanstack/router-utils

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

@tanstack/router-vite-plugin

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

@tanstack/solid-router

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

@tanstack/solid-router-devtools

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

@tanstack/solid-router-ssr-query

npm i https://pkg.pr.new/@tanstack/solid-router-ssr-query@8161

@tanstack/solid-start

npm i https://pkg.pr.new/@tanstack/solid-start@8161

@tanstack/solid-start-client

npm i https://pkg.pr.new/@tanstack/solid-start-client@8161

@tanstack/solid-start-server

npm i https://pkg.pr.new/@tanstack/solid-start-server@8161

@tanstack/start-client-core

npm i https://pkg.pr.new/@tanstack/start-client-core@8161

@tanstack/start-fn-stubs

npm i https://pkg.pr.new/@tanstack/start-fn-stubs@8161

@tanstack/start-plugin-core

npm i https://pkg.pr.new/@tanstack/start-plugin-core@8161

@tanstack/start-server-core

npm i https://pkg.pr.new/@tanstack/start-server-core@8161

@tanstack/start-static-server-functions

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

@tanstack/start-storage-context

npm i https://pkg.pr.new/@tanstack/start-storage-context@8161

@tanstack/valibot-adapter

npm i https://pkg.pr.new/@tanstack/valibot-adapter@8161

@tanstack/virtual-file-routes

npm i https://pkg.pr.new/@tanstack/virtual-file-routes@8161

@tanstack/vue-router

npm i https://pkg.pr.new/@tanstack/vue-router@8161

@tanstack/vue-router-devtools

npm i https://pkg.pr.new/@tanstack/vue-router-devtools@8161

@tanstack/vue-router-ssr-query

npm i https://pkg.pr.new/@tanstack/vue-router-ssr-query@8161

@tanstack/vue-start

npm i https://pkg.pr.new/@tanstack/vue-start@8161

@tanstack/vue-start-client

npm i https://pkg.pr.new/@tanstack/vue-start-client@8161

@tanstack/vue-start-server

npm i https://pkg.pr.new/@tanstack/vue-start-server@8161

@tanstack/zod-adapter

npm i https://pkg.pr.new/@tanstack/zod-adapter@8161

commit: 2b710ba

[github-actions]

Bundle Size Benchmarks

• Commit: 521e61d04085
• Measured at: 2026-08-24T21:23:57.765Z
• Baseline source: history:9f8990b51503
• Dashboard: bundle-size history

The following scenarios have bundle-size changes compared with the baseline:

Scenario	Current (gzip)	Initial (gzip)	Raw	Brotli	Trend
react-router.minimal	83.8 KiB +3 B	83.7 KiB +1 B	262.5 KiB +2 B	73.0 KiB +82 B	▆▆▅███▁▁▂▂▂▂
react-router.full	87.3 KiB +3 B	87.2 KiB +1 B	274.2 KiB +2 B	76.0 KiB +95 B	██▅███▁▁▂▂▂▂
solid-router.minimal	33.1 KiB +3 B	33.0 KiB +1 B	96.3 KiB +2 B	29.9 KiB +45 B	▇▇▇███▁▁▁▁▁▂
solid-router.full	38.0 KiB +3 B	37.9 KiB +2 B	111.0 KiB +2 B	34.2 KiB +18 B	██▆▇▇▇▁▁▂▂▂▂
vue-router.minimal	49.5 KiB +4 B	49.4 KiB +3 B	138.4 KiB +2 B	44.7 KiB +35 B	██▆███▁▁▂▂▂▂
vue-router.full	55.1 KiB +6 B	55.0 KiB +4 B	156.6 KiB +2 B	49.5 KiB +23 B	██▅▇▇▇▁▁▂▂▂▃
react-start.minimal	96.7 KiB +4 B	96.6 KiB +3 B	304.7 KiB +2 B	83.8 KiB +84 B	▆▆▃███▁▁▃▃▃▄
react-start.deferred-hydration	97.4 KiB +6 B	96.6 KiB +4 B	306.1 KiB +2 B	84.5 KiB +81 B	▆▆▄███▁▁▂▂▂▃
react-start.full	99.9 KiB +2 B	99.7 KiB +1 B	314.5 KiB +2 B	86.6 KiB -31 B	▅▅▃███▁▁▂▂▂▂
react-start.rsbuild.minimal	100.0 KiB +2 B	99.8 KiB +2 B	315.1 KiB +2 B	86.2 KiB -31 B	██▄▆▆▆▁▁▁▁▁▂
react-start.rsbuild.minimal-iife	100.4 KiB +2 B	100.3 KiB +2 B	316.0 KiB +2 B	86.6 KiB -83 B	██▄▆▆▆▁▁▁▁▁▂
react-start.rsbuild.full	103.3 KiB +2 B	103.2 KiB +2 B	325.2 KiB +2 B	89.1 KiB +51 B	██▅▆▆▆▁▁▁▁▁▂
solid-start.minimal	46.0 KiB +3 B	45.9 KiB +2 B	137.4 KiB +2 B	40.9 KiB -17 B	██▅███▁▁▁▁▁▁
solid-start.deferred-hydration	49.1 KiB +1 B	45.9 KiB +3 B	144.9 KiB +2 B	43.7 KiB -15 B	▇▇▃███▁▁▂▂▂▂
solid-start.full	51.1 KiB -1 B	51.0 KiB 0 B	152.8 KiB +2 B	45.3 KiB +21 B	▆▆▅███▁▁▁▁▁▁
vue-start.minimal	65.6 KiB +1 B	65.5 KiB +1 B	189.2 KiB +2 B	58.4 KiB -5 B	██▅███▁▁▃▃▃▃
vue-start.full	69.5 KiB -2 B	69.3 KiB -2 B	201.5 KiB +2 B	61.7 KiB +89 B	██▅███▁▁▃▃▃▂

Current gzip tracks all emitted client JS chunks. Initial gzip tracks only the entry/import graph. Trend sparkline is historical current gzip ending with this PR measurement; lower is better.

[codspeed-hq]

Merging this PR will regress 6 benchmarks

⚠️ Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

⚡ 9 improved benchmarks
❌ 6 regressed benchmarks
✅ 165 untouched benchmarks

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

	Mode	Benchmark	BASE	HEAD	Efficiency
❌	Memory	mem server serialization-payload (solid)	4.5 MB	7 MB	-34.94%
❌	Memory	mem server error-paths redirect (vue)	414.2 KB	473 KB	-12.43%
❌	Memory	mem server error-paths error (solid)	962.6 KB	1,084.5 KB	-11.24%
❌	Memory	mem server peak-large-page (vue)	1 MB	1.1 MB	-5.61%
❌	Memory	mem server server-fn-churn (react)	385.8 KB	399.7 KB	-3.48%
❌	Memory	mem server error-paths unmatched (solid)	565.9 KB	584.8 KB	-3.22%
⚡	Memory	mem server error-paths not-found (solid)	918.9 KB	595.2 KB	+54.39%
⚡	Memory	mem server aborted-requests (vue)	1,091.1 KB	1,013 KB	+7.71%
⚡	Memory	mem server server-fn-churn (solid)	345 KB	323.4 KB	+6.7%
⚡	Memory	mem server peak-large-page (react)	1.2 MB	1.1 MB	+4.66%
⚡	Memory	mem server error-paths not-found (react)	410.4 KB	393 KB	+4.45%
⚡	Simulation	client-async-pipeline navigation loop (react)	107.2 ms	102.9 ms	+4.18%
⚡	Memory	mem server aborted-requests (react)	886.6 KB	851.3 KB	+4.15%
⚡	Memory	mem server request-churn (solid)	734.5 KB	706.4 KB	+3.99%
⚡	Memory	mem server error-paths unmatched (vue)	602.9 KB	581.6 KB	+3.65%

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing fix/retain-not-found-boundary (2b710ba) with main (9f8990b)}