fix(router-core): stop preload after beforeLoad errors

[schiller-manuel]

Summary by CodeRabbit

• Bug Fixes
  • Fixed a preload behavior issue in nested routes where child route handlers would continue executing even after a parent route's beforeLoad handler failed. Preload operations now correctly terminate early when a parent handler encounters an error, preventing unnecessary execution of subsequent route handlers.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 5538b3cd-79b2-4d9d-8d58-78828e88a29f

📥 Commits

Reviewing files that changed from the base of the PR and between 4756d76 and e65b7ad.

📒 Files selected for processing (3)

• .changeset/green-turkeys-smile.md
• packages/router-core/src/load-matches.ts
• packages/router-core/tests/load.test.ts

---

📝 Walkthrough

Walkthrough

A patch update for @tanstack/router-core was released to fix premature execution of child route handlers. The preload operation now properly stops executing when a parent beforeLoad handler fails, preventing child beforeLoad and head handlers from continuing. The fix includes logic changes and test coverage.

Changes

Cohort / File(s)	Summary
Changeset .changeset/green-turkeys-smile.md	Added patch version changelog entry documenting the fix for preload behavior when parent beforeLoad handlers fail.
Load Execution Logic packages/router-core/src/load-matches.ts	Modified loadMatches to halt beforeLoad execution loop when firstBadMatchIndex is set, and decoupled headMaxIndex computation to depend solely on firstBadMatchIndex presence rather than serialError.
Test Coverage packages/router-core/tests/load.test.ts	Added test case verifying that child beforeLoad and head handlers do not execute when parent beforeLoad fails during preload operations.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 A preload that ran too far and wide,
Child handlers executing with undue pride,
Now parent checks halt the flow with care,
Stopping at the first bad match found there,
Clean execution paths, no longer lost in air! 🌟

🚥 Pre-merge checks | ✅ 2 | ❌ 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%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: fixing preload behavior to stop execution after beforeLoad errors in parent routes.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix-preload-beforeLoad

---

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

[nx-cloud]

View your CI Pipeline Execution ↗ for commit e65b7ad

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

---

☁️ Nx Cloud last updated this comment at 2026-03-30 21:40:19 UTC

[github-actions]

🚀 Changeset Version Preview

1 package(s) bumped directly, 21 bumped as dependents.

🟩 Patch bumps

Package	Version	Reason
@tanstack/router-core	1.168.7 → 1.168.8	Changeset
@tanstack/react-router	1.168.8 → 1.168.9	Dependent
@tanstack/react-start	1.167.14 → 1.167.15	Dependent
@tanstack/react-start-client	1.166.23 → 1.166.24	Dependent
@tanstack/react-start-server	1.166.23 → 1.166.24	Dependent
@tanstack/router-cli	1.166.23 → 1.166.24	Dependent
@tanstack/router-generator	1.166.22 → 1.166.23	Dependent
@tanstack/router-plugin	1.167.10 → 1.167.11	Dependent
@tanstack/router-vite-plugin	1.166.25 → 1.166.26	Dependent
@tanstack/solid-router	1.168.7 → 1.168.8	Dependent
@tanstack/solid-start	1.167.13 → 1.167.14	Dependent
@tanstack/solid-start-client	1.166.21 → 1.166.22	Dependent
@tanstack/solid-start-server	1.166.21 → 1.166.22	Dependent
@tanstack/start-client-core	1.167.7 → 1.167.8	Dependent
@tanstack/start-plugin-core	1.167.15 → 1.167.16	Dependent
@tanstack/start-server-core	1.167.7 → 1.167.8	Dependent
@tanstack/start-static-server-functions	1.166.23 → 1.166.24	Dependent
@tanstack/start-storage-context	1.166.21 → 1.166.22	Dependent
@tanstack/vue-router	1.168.7 → 1.168.8	Dependent
@tanstack/vue-start	1.167.13 → 1.167.14	Dependent
@tanstack/vue-start-client	1.166.21 → 1.166.22	Dependent
@tanstack/vue-start-server	1.166.21 → 1.166.22	Dependent

[github-actions]

Bundle Size Benchmarks

• Commit: 4756d760ca00
• Measured at: 2026-03-30T21:33:22.754Z
• Baseline source: history:f8351a8d7aa9
• Dashboard: bundle-size history

Scenario	Current (gzip)	Delta vs baseline	Raw	Brotli	Trend
react-router.minimal	87.48 KiB	+8 B (+0.01%)	275.72 KiB	76.00 KiB	██▃▃▃▃▁▁▁▁▁▁
react-router.full	90.77 KiB	+6 B (+0.01%)	286.90 KiB	78.80 KiB	██▄▄▄▅▁▁▁▁▁▁
solid-router.minimal	35.52 KiB	+6 B (+0.02%)	107.08 KiB	31.87 KiB	██▃▃▃▃▁▁▁▁▁▁
solid-router.full	39.99 KiB	+5 B (+0.01%)	120.62 KiB	35.87 KiB	██▆▆▆▆▁▁▁▁▁▁
vue-router.minimal	53.37 KiB	+7 B (+0.01%)	153.01 KiB	47.90 KiB	██████▁▁▁▁▁▂
vue-router.full	58.23 KiB	+6 B (+0.01%)	168.47 KiB	52.16 KiB	██▆▆▆▆▁▁▁▁▁▂
react-start.minimal	102.00 KiB	+5 B (+0.00%)	323.96 KiB	88.19 KiB	██▄▄▄▅▁▁▁▂▂▂
react-start.full	105.37 KiB	+8 B (+0.01%)	334.31 KiB	91.10 KiB	██▄▄▄▅▁▁▁▁▁▂
solid-start.minimal	49.62 KiB	+6 B (+0.01%)	153.33 KiB	43.77 KiB	██▄▄▄▄▁▁▁▁▁▂
solid-start.full	55.11 KiB	+11 B (+0.02%)	169.57 KiB	48.46 KiB	██▅▅▅▅▁▁▁▁▁▂

Trend sparkline is historical gzip bytes ending with this PR measurement; lower is better.

[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-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-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-rsc
• 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-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/arktype-adapter@7075

@tanstack/eslint-plugin-router

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

@tanstack/history

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

@tanstack/nitro-v2-vite-plugin

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

@tanstack/react-router

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

@tanstack/react-router-devtools

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

@tanstack/react-router-ssr-query

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

@tanstack/react-start

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

@tanstack/react-start-client

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

@tanstack/react-start-server

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

@tanstack/router-cli

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

@tanstack/router-core

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

@tanstack/router-devtools

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

@tanstack/router-devtools-core

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

@tanstack/router-generator

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

@tanstack/router-plugin

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

@tanstack/router-ssr-query-core

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

@tanstack/router-utils

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

@tanstack/router-vite-plugin

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

@tanstack/solid-router

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

@tanstack/solid-router-devtools

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

@tanstack/solid-router-ssr-query

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

@tanstack/solid-start

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

@tanstack/solid-start-client

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

@tanstack/solid-start-server

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

@tanstack/start-client-core

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

@tanstack/start-fn-stubs

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

@tanstack/start-plugin-core

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

@tanstack/start-server-core

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

@tanstack/start-static-server-functions

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

@tanstack/start-storage-context

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

@tanstack/valibot-adapter

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

@tanstack/virtual-file-routes

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

@tanstack/vue-router

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

@tanstack/vue-router-devtools

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

@tanstack/vue-router-ssr-query

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

@tanstack/vue-start

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

@tanstack/vue-start-client

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

@tanstack/vue-start-server

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

@tanstack/zod-adapter

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

commit: e65b7ad

[codspeed-hq]

Merging this PR will not alter performance

✅ 6 untouched benchmarks

---

_{Comparing fix-preload-beforeLoad (e65b7ad) with main (f8351a8)¹}

Footnotes

1. No successful run was found on main (4756d76) during the generation of this report, so f8351a8 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩