fix(react-router): Catch thrown nullish value and prevent nullish

[joseinaqa]

loadPromise from being thrown

The issue happens in circumstances where match.status === 'redirected' but the loadPromise is nulled.
Reproduction is possible by using
https://github.com/joseinaqa/redirect-race-app and after this change does not happen anymore.

Summary by CodeRabbit

• Bug Fixes
  • Improved error handling by normalizing falsy “thrown” values so error boundaries always receive a real Error.
  • Preserved component stack trace details when available, improving diagnostics for caught errors.
  • Fixed Suspense/loading behavior so “pending” rendering doesn’t break when match resolution can be temporarily unavailable.
  • Ensured client-side rethrows always raise a concrete error instead of a potentially missing value.

[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: 59f99bcb-9133-4bc0-8197-7b06fffea930

📥 Commits

Reviewing files that changed from the base of the PR and between 61fa627 and de1aaf2.

📒 Files selected for processing (2)

• packages/react-router/src/CatchBoundary.tsx
• packages/react-router/src/Match.tsx

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

• packages/react-router/src/CatchBoundary.tsx
• packages/react-router/src/Match.tsx

---

📝 Walkthrough

Walkthrough

CatchBoundary now normalizes nullish thrown errors and updates the stored stack before calling onCatch. Match now falls back to a shared never-resolving promise when Suspense would otherwise throw nothing, and client error rethrows now always produce a concrete Error.

Changes

Error and Suspense Handling Fixes

Layer / File(s)	Summary
Nullish error normalization in CatchBoundary packages/react-router/src/CatchBoundary.tsx	Nullish thrown errors are replaced with a new Error, componentDidCatch patches the stored error's stack, and onCatch receives the normalized error.
permaPendingPromise fallback for Suspense throws packages/react-router/src/Match.tsx	A shared permaPendingPromise is introduced and used as a fallback across server and client pending, redirect, and error throw sites to ensure a Promise is always thrown for Suspense.

Estimated code review effort: 2 (Simple) | ~12 minutes

Possibly related issues

• MatchInner can throw undefined when a redirected match's loadPromise was already cleared — escapes CatchBoundary and unmounts the whole app #7753: The changes address the same MatchInner/CatchBoundarythrow undefined failure mode described in this issue.
• Uncaught undefined in in the <MatchInnerImpl> component #7457: The MatchInner updates prevent throwing undefined during pending/redirect/error paths, matching the reported <MatchInnerImpl> bug.

Possibly related PRs

• TanStack/router#7505: Changes in CatchBoundary and Match normalize or fall back when caught or thrown error values are falsy or undefined, which is closely related to this PR.

Suggested labels:package: react-router

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is relevant to the main fix: handling thrown nullish values in react-router.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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 unit tests (beta)

• Create PR with unit tests

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 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/src/Match.tsx`:
- Line 523: The Match.tsx error-handling path currently throws
permaPendingPromise when match.error is nullish, which keeps the route suspended
instead of reaching the error boundary. Update the logic in Match to throw a
synthetic Error in this branch, and keep using match.error when present so
client error states render correctly rather than staying on the pending
fallback.

🪄 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: a7b45fc0-6aa0-4f09-8dcf-8eda61c7602c

📥 Commits

Reviewing files that changed from the base of the PR and between 208100b and dbd4754.

📒 Files selected for processing (2)

• packages/react-router/src/CatchBoundary.tsx
• packages/react-router/src/Match.tsx

[tristansinclair]

We hit this exact crash in production and independently arrived at essentially this same diff before finding this PR — so consider this a field test of the approach. Stack: React 19.2 SPA (no SSR), Vite, @tanstack/react-router 1.169.1 + TanStack Query, Clerk for auth, Sentry for error reporting. Sharing the evidence since the PR has no review yet:

Debugger-confirmed throw site. Sentry only showed a stackless Uncaught undefined (thrown undefined has no stack; the single frame is React's defaultOnUncaughtError → reportError). With CDP Debugger.setPauseOnExceptions('all') filtered to exception values of type undefined, every pause landed on throw getMatchPromise(match, 'loadPromise') in MatchInnerImpl — in our runs specifically the status === 'pending' branch — 16 throws in a single page load. The thrown undefined then escaped every CatchBoundary (falsy if (error) check), React unmounted the root, and users got a permanent white screen.

Deterministic reproduction shape. Cold load at / where beforeLoad awaits async work for a few hundred ms (for us: waiting on clerk-js readiness, then an API fetch) and finally throw redirect(...), with defaultPendingComponent set, defaultPendingMs: 200, defaultPendingMinMs: 300. Driving that flow headlessly against our real app: 6/6 cold loads crashed on stock 1.169.1.

This PR's approach fixes it. We shipped the equivalent change as a dist patch (below) and re-ran the same harness: 0/13 crashes across the same conditions and harsher variants (CPU-throttled, delayed auth responses, multi-hop redirect chains), with all navigations completing normally.

Also verified the affected code is byte-identical in the latest release (1.170.17), so this isn't fixed by upgrading.

One correctness nit: getDerivedStateFromError normalizes with error ?? new Error(...), but the render callback checks truthiness (if (error)). A thrown 0, '', false, or NaN is non-nullish yet falsy, so it still slips through the boundary and unmounts the app the same way. error || new Error(...) closes the gap completely — an error boundary can't meaningfully render a falsy error anyway, so there's no behavior worth preserving there.

For anyone needing a stopgap while this PR is pending, here's the dist-level patch we're running in production via bun patch (same idea works with pnpm patch / patch-package):

@tanstack/react-router@1.169.1 dist patch (esm + cjs)

diff --git a/dist/esm/Match.js b/dist/esm/Match.js--- a/dist/esm/Match.js+++ b/dist/esm/Match.js@@ -128,7 +128,7 @@ function OnRendered({ resetKey }) {
var MatchInner = React$1.memo(function MatchInnerImpl({ matchId }) {
const router = useRouter();
const getMatchPromise = (match, key) => {
- return router.getMatch(match.id)?._nonReactive[key] ?? match._nonReactive[key];+ return router.getMatch(match.id)?._nonReactive[key] ?? match._nonReactive[key] ?? new Promise(() => {});
};
if (isServer ?? router.isServer) {
const match = router.stores.matchStores.get(matchId)?.get();
diff --git a/dist/esm/CatchBoundary.js b/dist/esm/CatchBoundary.js--- a/dist/esm/CatchBoundary.js+++ b/dist/esm/CatchBoundary.js@@ -30,7 +30,7 @@ var CatchBoundaryImpl = class extends React$1.Component {
return { resetKey };
}
static getDerivedStateFromError(error) {
- return { error };+ return { error: error || new Error(`Unhandled falsy error: ${String(error)}`) };
}
reset() {
this.setState({ error: null });
diff --git a/dist/cjs/Match.cjs b/dist/cjs/Match.cjs--- a/dist/cjs/Match.cjs+++ b/dist/cjs/Match.cjs@@ -130,7 +130,7 @@ function OnRendered({ resetKey }) {
var MatchInner = react.memo(function MatchInnerImpl({ matchId }) {
const router = require_useRouter.useRouter();
const getMatchPromise = (match, key) => {
- return router.getMatch(match.id)?._nonReactive[key] ?? match._nonReactive[key];+ return router.getMatch(match.id)?._nonReactive[key] ?? match._nonReactive[key] ?? new Promise(() => {});
};
if (_tanstack_router_core_isServer.isServer ?? router.isServer) {
const match = router.stores.matchStores.get(matchId)?.get();
diff --git a/dist/cjs/CatchBoundary.cjs b/dist/cjs/CatchBoundary.cjs--- a/dist/cjs/CatchBoundary.cjs+++ b/dist/cjs/CatchBoundary.cjs@@ -32,7 +32,7 @@ var CatchBoundaryImpl = class extends react.Component {
return { resetKey };
}
static getDerivedStateFromError(error) {
- return { error };+ return { error: error || new Error(`Unhandled falsy error: ${String(error)}`) };
}
reset() {
this.setState({ error: null });

Patching getMatchPromise itself covers all four throw sites (displayPendingPromise, minPendingPromise, and both loadPromise branches) with one hunk per module format. A missing promise means the match is being torn down mid-transition, so suspending forever is safe — React discards the suspended subtree as soon as the router commits the new matches.

Related reports this would resolve: #7753, #7457, #7367 (and it overlaps the scenario in #7120 / #7158).