fix(router-core): preserve replacement promises on loader abort

[LadyBluenotes]

Summary by CodeRabbit

• Bug Fixes
  • Fixed rapid search/filter navigations to keep the latest loaded data displayed.
  • Prevented aborted loader executions from interfering with newer in-flight loads for the same route match.
  • Improved concurrent loading behavior during background revalidation, including correct suppression of error UI when a newer load supersedes a failing/aborted one.
• Tests
  • Added a regression test covering aborting a reused parent match without clearing the replacement load promise.
• Release
  • Patch release for router-core.

[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: 9d8e58ab-8309-4fde-ba8a-9a3d241b10f5

📥 Commits

Reviewing files that changed from the base of the PR and between 10d8fc0 and ebca5c7.

📒 Files selected for processing (1)

• packages/react-router/tests/loaders.test.tsx

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/react-router/tests/loaders.test.tsx

---

📝 Walkthrough

Walkthrough

Loader matching now tracks controlled promises per route match, prevents stale aborted loads from clearing replacement promises, and coordinates loader finalization. A regression test covers rapid search updates with reused parent matches.

Changes

Loader promise lifecycle

Layer / File(s)	Summary
Per-match promise tracking packages/router-core/src/load-matches.ts	Adds per-index controlled promise storage and records replacement promises during beforeLoad and load initialization.
Load finalization and regression coverage packages/router-core/src/load-matches.ts, packages/react-router/tests/loaders.test.tsx, .changeset/eight-feet-lose.md	Uses identity checks when resolving and clearing promises, updates abort handling, tests rapid search updates, and records a patch release.

Estimated code review effort: 4 (Complex) | ~45 minutes

Possibly related issues

• perf(router-core): evaluate synchronous loadRouteMatch fast paths #7791 — Related to controlled loaderPromise and loadPromise lifecycle handling in loadRouteMatch; this PR addresses stale-abort cleanup rather than synchronous fast paths.

Suggested reviewers: sheraff

🚥 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%.	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 accurately captures the main fix: aborted loaders no longer clear newer replacement promises in router-core.
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

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/abort-error-loader-race

---

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 ebca5c7

Command	Status	Duration	Result
nx affected --targets=test:eslint,test:unit,tes...	❌ Failed	5m 22s	View ↗
nx run-many --target=build --exclude=examples/*...	✅ Succeeded	25s	View ↗

---

☁️ Nx Cloud last updated this comment at 2026-07-14 04:18:25 UTC

[github-actions]

🚀 Changeset Version Preview

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

🟩 Patch bumps

Package	Version	Reason
@tanstack/router-core	1.171.15 → 1.171.16	Changeset
@tanstack/react-router	1.170.18 → 1.170.19	Dependent
@tanstack/react-start	1.168.28 → 1.168.29	Dependent
@tanstack/react-start-client	1.168.16 → 1.168.17	Dependent
@tanstack/react-start-rsc	0.1.27 → 0.1.28	Dependent
@tanstack/react-start-server	1.167.22 → 1.167.23	Dependent
@tanstack/router-cli	1.167.19 → 1.167.20	Dependent
@tanstack/router-generator	1.167.19 → 1.167.20	Dependent
@tanstack/router-plugin	1.168.20 → 1.168.21	Dependent
@tanstack/router-vite-plugin	1.167.20 → 1.167.21	Dependent
@tanstack/solid-router	1.170.18 → 1.170.19	Dependent
@tanstack/solid-start	1.168.28 → 1.168.29	Dependent
@tanstack/solid-start-client	1.168.16 → 1.168.17	Dependent
@tanstack/solid-start-server	1.167.22 → 1.167.23	Dependent
@tanstack/start-client-core	1.170.14 → 1.170.15	Dependent
@tanstack/start-plugin-core	1.171.20 → 1.171.21	Dependent
@tanstack/start-server-core	1.169.17 → 1.169.18	Dependent
@tanstack/start-static-server-functions	1.167.19 → 1.167.20	Dependent
@tanstack/start-storage-context	1.167.17 → 1.167.18	Dependent
@tanstack/vue-router	1.170.17 → 1.170.18	Dependent
@tanstack/vue-start	1.168.27 → 1.168.28	Dependent
@tanstack/vue-start-client	1.167.19 → 1.167.20	Dependent
@tanstack/vue-start-server	1.167.22 → 1.167.23	Dependent

[github-actions]

Bundle Size Benchmarks

• Commit: 8b92316c29b2
• Measured at: 2026-07-14T04:14:09.762Z
• Baseline source: history:11a6a0d8ba4d
• Dashboard: bundle-size history

Scenario	Current (gzip)	Delta vs baseline	Initial gzip	Raw	Brotli	Trend
react-router.minimal	87.39 KiB	+40 B (+0.04%)	87.25 KiB	273.70 KiB	75.96 KiB	▁▁▆▆▆▆▆▆▃▃▃█
react-router.full	91.11 KiB	+49 B (+0.05%)	90.97 KiB	285.60 KiB	79.11 KiB	▁▁▇▇▇▇▇▇▁▁▁█
solid-router.minimal	35.58 KiB	+56 B (+0.15%)	35.46 KiB	105.89 KiB	32.07 KiB	▁▁▆▆▆▆▆▆▁▁▁█
solid-router.full	40.63 KiB	+45 B (+0.11%)	40.50 KiB	121.11 KiB	36.56 KiB	▁▁▆▆▆▆▆▆▁▁▁█
vue-router.minimal	53.05 KiB	+55 B (+0.10%)	52.92 KiB	149.93 KiB	47.65 KiB	▂▂██████▁▁▁▇
vue-router.full	58.99 KiB	+50 B (+0.08%)	58.86 KiB	168.69 KiB	52.80 KiB	▅▅██████▁▁▁▅
react-start.minimal	102.04 KiB	+54 B (+0.05%)	101.90 KiB	322.13 KiB	88.22 KiB	▁▄▇▇▇▇▇▇▄▄▄█
react-start.deferred-hydration	102.78 KiB	+57 B (+0.05%)	101.92 KiB	323.50 KiB	89.04 KiB	▁▃▇▇▇▇▇▇▃▃▃█
react-start.full	105.42 KiB	+54 B (+0.05%)	105.28 KiB	332.06 KiB	91.12 KiB	▁▄██████▁▁▁▆
react-start.rsbuild.minimal	99.75 KiB	+78 B (+0.08%)	99.58 KiB	316.56 KiB	85.83 KiB	▁▄▇▇▇▇▇▇▃▃▃█
react-start.rsbuild.minimal-iife	100.16 KiB	+79 B (+0.08%)	99.99 KiB	317.50 KiB	86.29 KiB	▁▄▇▇▇▇▇▇▃▃▃█
react-start.rsbuild.full	102.99 KiB	+96 B (+0.09%)	102.82 KiB	326.62 KiB	88.58 KiB	▁▃▆▆▆▆▆▆▂▂▂█
solid-start.minimal	49.65 KiB	+43 B (+0.08%)	49.52 KiB	152.06 KiB	43.90 KiB	▃▅██████▁▁▁▄
solid-start.deferred-hydration	52.91 KiB	+42 B (+0.08%)	49.58 KiB	160.10 KiB	46.85 KiB	▃▅██████▁▁▁▄
solid-start.full	55.47 KiB	+53 B (+0.09%)	55.34 KiB	169.11 KiB	48.91 KiB	▃▆██████▁▁▁▅
vue-start.minimal	71.08 KiB	+54 B (+0.07%)	70.95 KiB	207.18 KiB	62.95 KiB	▄▇██████▁▁▁▅
vue-start.full	75.08 KiB	+50 B (+0.07%)	74.95 KiB	219.82 KiB	66.45 KiB	▃▅██████▁▁▁▄

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.

[pkg-pr-new]

More templates

• 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-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-router-vue-example-basic-jsx
• tanstack-router-vue-example-basic-file-based-jsx
• tanstack-router-vue-example-basic-file-based-sfc

@tanstack/arktype-adapter

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

@tanstack/eslint-plugin-router

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

@tanstack/eslint-plugin-start

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

@tanstack/history

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

@tanstack/nitro-v2-vite-plugin

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

@tanstack/react-router

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

@tanstack/react-router-devtools

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

@tanstack/react-router-ssr-query

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

@tanstack/react-start

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

@tanstack/react-start-client

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

@tanstack/react-start-rsc

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

@tanstack/react-start-server

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

@tanstack/router-cli

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

@tanstack/router-core

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

@tanstack/router-devtools

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

@tanstack/router-devtools-core

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

@tanstack/router-generator

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

@tanstack/router-plugin

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

@tanstack/router-ssr-query-core

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

@tanstack/router-utils

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

@tanstack/router-vite-plugin

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

@tanstack/solid-router

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

@tanstack/solid-router-devtools

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

@tanstack/solid-router-ssr-query

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

@tanstack/solid-start

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

@tanstack/solid-start-client

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

@tanstack/solid-start-server

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

@tanstack/start-client-core

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

@tanstack/start-fn-stubs

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

@tanstack/start-plugin-core

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

@tanstack/start-server-core

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

@tanstack/start-static-server-functions

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

@tanstack/start-storage-context

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

@tanstack/valibot-adapter

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

@tanstack/virtual-file-routes

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

@tanstack/vue-router

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

@tanstack/vue-router-devtools

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

@tanstack/vue-router-ssr-query

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

@tanstack/vue-start

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

@tanstack/vue-start-client

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

@tanstack/vue-start-server

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

@tanstack/zod-adapter

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

commit: ebca5c7

[nx-cloud]

Important

At least one additional CI pipeline execution has run since the conclusion below was written and it may no longer be applicable.

Nx Cloud has identified a possible root cause for your failed CI:

We determined this failure is unrelated to the PR's changes. The tanstack-solid-start-e2e-basic e2e test failed because port 44231 was already in use in the CI environment (EADDRINUSE), preventing the test server from starting. Our analysis confirms the PR only touched @tanstack/react-router and @tanstack/router-core, so this is an environment-level issue that requires a re-run.

No code changes were suggested for this issue.

Trigger a rerun:

View detailed reasoning on Nx Cloud ↗

_{🎓 Learn more about Self-Healing CI on nx.dev}

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

packages/router-core/src/load-matches.ts (1)

777-784: 🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win

Guard the loaderPromise reset in the outer catch packages/router-core/src/load-matches.ts:777-784 still clears match._nonReactive.loaderPromise unconditionally; that can wipe out a newer in-flight load’s promise.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/router-core/src/load-matches.ts` around lines 777 - 784, Update the
outer catch around handleRedirectAndNotFound to reset
match._nonReactive.loaderPromise only when it still refers to the failed load’s
promise, preserving any newer in-flight loader promise. Use the existing loader
promise captured by the surrounding load flow and retain the missing-match
guard.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/react-router/tests/loaders.test.tsx`:
- Around line 1013-1023: Update the test around the filter-change loop to verify
that the root loader actually reruns for the reused parent match, rather than
only asserting its in-flight request was aborted. Assert the root loader mock’s
call count or configure the root route to depend on the navigation, while
preserving the existing abort and error-component assertions.

---

Outside diff comments:
In `@packages/router-core/src/load-matches.ts`:
- Around line 777-784: Update the outer catch around handleRedirectAndNotFound
to reset match._nonReactive.loaderPromise only when it still refers to the
failed load’s promise, preserving any newer in-flight loader promise. Use the
existing loader promise captured by the surrounding load flow and retain the
missing-match guard.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 163b889e-c1dd-4e3c-8e15-7c2e75806f38

📥 Commits

Reviewing files that changed from the base of the PR and between 11a6a0d and 23cc7b8.

📒 Files selected for processing (2)

• packages/react-router/tests/loaders.test.tsx
• packages/router-core/src/load-matches.ts

[codspeed-hq]

Merging this PR will degrade performance by 24.12%

⚠️ 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

⚡ 5 improved benchmarks
❌ 7 regressed benchmarks
✅ 168 untouched benchmarks

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

	Mode	Benchmark	BASE	HEAD	Efficiency
❌	Memory	mem server server-fn-churn (vue)	274.8 KB	4,248.2 KB	-93.53%
❌	Memory	mem server error-paths redirect (vue)	304.3 KB	778.3 KB	-60.91%
❌	Memory	mem server error-paths redirect (solid)	441 KB	832.7 KB	-47.03%
❌	Memory	mem server error-paths unmatched (react)	641.2 KB	770.4 KB	-16.77%
❌	Simulation	client-preload interaction loop (react)	57.3 ms	60.6 ms	-5.41%
❌	Simulation	client-route-tree-scale navigation loop (react)	74.2 ms	77.2 ms	-3.9%
❌	Memory	mem server error-paths not-found (react)	266.8 KB	276.3 KB	-3.44%
⚡	Memory	mem server peak-large-page (react)	2,080.9 KB	953.8 KB	×2.2
⚡	Memory	mem server serialization-payload (react)	5.3 MB	3.4 MB	+53.32%
⚡	Simulation	ssr selective (react)	64.3 ms	61.9 ms	+3.78%
⚡	Simulation	ssr selective (solid)	74.7 ms	72 ms	+3.7%
⚡	Simulation	ssr streaming deferred (react)	73.1 ms	70.7 ms	+3.42%

Tip

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

---

_{Comparing fix/abort-error-loader-race (ebca5c7) with main (11a6a0d)}