Skip to content

fix: preserve render-thrown notFound errors#7077

Merged
schiller-manuel merged 2 commits intomainfrom
fix-notfound-comp
Mar 30, 2026
Merged

fix: preserve render-thrown notFound errors#7077
schiller-manuel merged 2 commits intomainfrom
fix-notfound-comp

Conversation

@schiller-manuel
Copy link
Copy Markdown
Contributor

@schiller-manuel schiller-manuel commented Mar 30, 2026

Summary by CodeRabbit

  • Bug Fixes

    • Route-thrown notFound() errors now retain their route context when crossing framework boundaries, so the correct route-specific notFoundComponent is rendered (supports React, Solid, and Vue, including fuzzy notFound mode).
  • Tests

    • Added test coverage validating notFound() behavior in multi-level route hierarchies and fallback selection.

@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai bot commented Mar 30, 2026

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b18385dc-e148-431e-b113-42e324b8f2c9

📥 Commits

Reviewing files that changed from the base of the PR and between f07ccba and a8b1068.

📒 Files selected for processing (1)
  • packages/solid-router/src/not-found.tsx

📝 Walkthrough

Walkthrough

Annotates framework-thrown notFound() errors with the current match's routeId when missing, and normalizes Solid-wrapped not-found values; updates catch/not-found boundaries across React, Solid, and Vue to use the annotated value so route-specific notFoundComponent handlers render correctly.

Changes

Cohort / File(s) Summary
Changesets Release Declaration
\.changeset/funny-doors-smile.md
Adds a changeset declaring patch releases for @tanstack/router-core, @tanstack/react-router, @tanstack/solid-router, and @tanstack/vue-router documenting the notFound boundary behavior change.
React Router Match Handling
packages/react-router/src/Match.tsx
When a not-found error is caught, assign error.routeId from current matchState.routeId if missing before rethrowing or handing to not-found fallback.
React Router Tests
packages/react-router/tests/not-found.test.tsx
Adds two tests for notFoundMode: 'fuzzy' covering component-thrown bare notFound() resolving to the correct route-level notFoundComponent.
Solid Router: helper & Match
packages/solid-router/src/not-found.tsx, packages/solid-router/src/Match.tsx
Adds exported getNotFound(error) to normalize Solid-wrapped not-found values; uses it and annotates notFoundError.routeId in catch/not-found handlers, and forwards normalized not-found into render props.
Solid Router Tests
packages/solid-router/tests/not-found.test.tsx
Adds two tests validating route/component-thrown notFound() behavior with hierarchical not-found component resolution.
Vue Router Match Handling
packages/vue-router/src/Match.tsx
Annotates not-found errors with current match routeId in catch/fallback paths to ensure proper route-specific not-found rendering.
Vue Router Tests
packages/vue-router/tests/not-found.test.tsx
Adds two tests for notFound() thrown from components verifying the nearest boundary with a notFoundComponent renders.

Sequence Diagram

sequenceDiagram
    participant RouteComponent as Route Component
    participant CatchBoundary as Catch / NotFound Boundary
    participant RouteMatch as Route Match State
    participant NotFoundHandler as Route NotFound Component

    RouteComponent->>CatchBoundary: throw notFound()
    CatchBoundary->>RouteMatch: read currentMatchState().routeId
    CatchBoundary->>CatchBoundary: error.routeId ??= matchState.routeId
    CatchBoundary->>NotFoundHandler: invoke fallback / render with annotated error
    NotFoundHandler->>RouteMatch: compare error.routeId vs currentMatch.routeId
    alt routeId matches current route
        NotFoundHandler->>NotFoundHandler: render route's notFoundComponent
    else routeId doesn't match
        NotFoundHandler->>CatchBoundary: rethrow to parent boundary
    end
Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

Poem

🐰 I hopped through boundaries, ears all bright,

notFound() tucked with routeId right,
From React to Solid and Vue I prance,
The proper handler gets its chance,
A carrot cheer for tidy error dance 🥕

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 50.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 describes the main fix: ensuring that notFound() errors thrown from route components are preserved through framework error boundaries so they can be properly handled by notFoundComponent handlers.

✏️ 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-notfound-comp

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

@nx-cloud
Copy link
Copy Markdown
Contributor

nx-cloud bot commented Mar 30, 2026

View your CI Pipeline Execution ↗ for commit a8b1068

Command Status Duration Result
nx run-many --target=build --exclude=examples/*... ✅ Succeeded 33s View ↗

☁️ Nx Cloud last updated this comment at 2026-03-30 23:10:52 UTC

@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Mar 30, 2026

🚀 Changeset Version Preview

4 package(s) bumped directly, 18 bumped as dependents.

🟩 Patch bumps

Package Version Reason
@tanstack/react-router 1.168.9 → 1.168.10 Changeset
@tanstack/router-core 1.168.8 → 1.168.9 Changeset
@tanstack/solid-router 1.168.8 → 1.168.9 Changeset
@tanstack/vue-router 1.168.8 → 1.168.9 Changeset
@tanstack/react-start 1.167.15 → 1.167.16 Dependent
@tanstack/react-start-client 1.166.24 → 1.166.25 Dependent
@tanstack/react-start-server 1.166.24 → 1.166.25 Dependent
@tanstack/router-cli 1.166.24 → 1.166.25 Dependent
@tanstack/router-generator 1.166.23 → 1.166.24 Dependent
@tanstack/router-plugin 1.167.11 → 1.167.12 Dependent
@tanstack/router-vite-plugin 1.166.26 → 1.166.27 Dependent
@tanstack/solid-start 1.167.14 → 1.167.15 Dependent
@tanstack/solid-start-client 1.166.22 → 1.166.23 Dependent
@tanstack/solid-start-server 1.166.22 → 1.166.23 Dependent
@tanstack/start-client-core 1.167.8 → 1.167.9 Dependent
@tanstack/start-plugin-core 1.167.16 → 1.167.17 Dependent
@tanstack/start-server-core 1.167.8 → 1.167.9 Dependent
@tanstack/start-static-server-functions 1.166.24 → 1.166.25 Dependent
@tanstack/start-storage-context 1.166.22 → 1.166.23 Dependent
@tanstack/vue-start 1.167.14 → 1.167.15 Dependent
@tanstack/vue-start-client 1.166.22 → 1.166.23 Dependent
@tanstack/vue-start-server 1.166.22 → 1.166.23 Dependent

@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Mar 30, 2026

Bundle Size Benchmarks

  • Commit: d1174179082d
  • Measured at: 2026-03-30T22:57:37.718Z
  • Baseline source: history:2d1ec865a446
  • Dashboard: bundle-size history
Scenario Current (gzip) Delta vs baseline Raw Brotli Trend
react-router.minimal 87.48 KiB +7 B (+0.01%) 275.76 KiB 75.97 KiB █▃▃▃▃▁▁▁▁▁▁▂
react-router.full 90.78 KiB +7 B (+0.01%) 286.95 KiB 78.95 KiB █▄▄▄▅▁▁▁▁▁▁▂
solid-router.minimal 35.56 KiB +46 B (+0.13%) 107.26 KiB 31.94 KiB █▃▃▃▃▁▁▁▁▁▁▃
solid-router.full 40.03 KiB +39 B (+0.10%) 120.79 KiB 35.94 KiB █▆▆▆▆▁▁▁▁▁▁▄
vue-router.minimal 53.38 KiB +14 B (+0.03%) 153.07 KiB 47.94 KiB █████▁▁▁▁▁▂▃
vue-router.full 58.25 KiB +17 B (+0.03%) 168.53 KiB 52.18 KiB █▆▆▆▆▁▁▁▁▁▂▃
react-start.minimal 102.01 KiB +8 B (+0.01%) 324.00 KiB 88.21 KiB █▄▄▄▅▁▁▁▂▂▂▂
react-start.full 105.38 KiB +9 B (+0.01%) 334.35 KiB 91.14 KiB █▄▄▄▅▁▁▁▁▁▂▂
solid-start.minimal 49.66 KiB +48 B (+0.09%) 153.51 KiB 43.84 KiB █▄▄▄▄▁▁▁▁▁▂▄
solid-start.full 55.17 KiB +60 B (+0.11%) 169.74 KiB 48.46 KiB █▅▅▅▅▁▁▁▁▁▂▅

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

@pkg-pr-new
Copy link
Copy Markdown

pkg-pr-new bot commented Mar 30, 2026

More templates

@tanstack/arktype-adapter

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

@tanstack/eslint-plugin-router

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

@tanstack/history

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

@tanstack/nitro-v2-vite-plugin

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

@tanstack/react-router

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

@tanstack/react-router-devtools

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

@tanstack/react-router-ssr-query

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

@tanstack/react-start

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

@tanstack/react-start-client

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

@tanstack/react-start-server

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

@tanstack/router-cli

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

@tanstack/router-core

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

@tanstack/router-devtools

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

@tanstack/router-devtools-core

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

@tanstack/router-generator

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

@tanstack/router-plugin

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

@tanstack/router-ssr-query-core

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

@tanstack/router-utils

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

@tanstack/router-vite-plugin

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

@tanstack/solid-router

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

@tanstack/solid-router-devtools

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

@tanstack/solid-router-ssr-query

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

@tanstack/solid-start

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

@tanstack/solid-start-client

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

@tanstack/solid-start-server

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

@tanstack/start-client-core

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

@tanstack/start-fn-stubs

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

@tanstack/start-plugin-core

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

@tanstack/start-server-core

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

@tanstack/start-static-server-functions

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

@tanstack/start-storage-context

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

@tanstack/valibot-adapter

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

@tanstack/virtual-file-routes

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

@tanstack/vue-router

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

@tanstack/vue-router-devtools

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

@tanstack/vue-router-ssr-query

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

@tanstack/vue-start

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

@tanstack/vue-start-client

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

@tanstack/vue-start-server

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

@tanstack/zod-adapter

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

commit: f07ccba

Copy link
Copy Markdown
Contributor

@nx-cloud nx-cloud bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

❌ The fix was rejected

We add a dedicated NotFoundErrorPlugin for seroval that must be registered before ShallowErrorPlugin, because notFound() now returns an Error instance and ShallowErrorPlugin only preserves the message property — silently dropping isNotFound, routeId, data, and other metadata on every SSR/hydration cycle. This fix ensures all NotFoundError properties survive dehydration and rehydration, restoring correct not-found boundary resolution on the client.

Suggested Fix changes
diff --git a/packages/router-core/src/ssr/serializer/NotFoundErrorPlugin.ts b/packages/router-core/src/ssr/serializer/NotFoundErrorPlugin.ts
new file mode 100644
index 0000000000..5947d88e02
--- /dev/null
+++ b/packages/router-core/src/ssr/serializer/NotFoundErrorPlugin.ts
@@ -0,0 +1,81 @@
+import { createPlugin } from 'seroval'
+import type { SerovalNode } from 'seroval'
+
+interface NotFoundNode {
+  message: SerovalNode
+  routeId: SerovalNode
+  data: SerovalNode
+  global: SerovalNode
+  _global: SerovalNode
+}
+
+/**
+ * Serializes NotFoundError instances (objects with `isNotFound: true`) so that
+ * all router metadata (routeId, data, global, _global) survives SSR dehydration
+ * and client-side hydration.  This plugin must be registered before
+ * ShallowErrorPlugin because notFound() now returns an Error subclass – without
+ * this plugin ShallowErrorPlugin would match first and strip all custom
+ * properties, keeping only `message`.
+ */
+export const NotFoundErrorPlugin = /* @__PURE__ */ createPlugin<
+  any,
+  NotFoundNode
+>({
+  tag: '$TSR/NotFoundError',
+  test(value) {
+    return !!value?.isNotFound
+  },
+  parse: {
+    sync(value, ctx) {
+      return {
+        message: ctx.parse(value.message),
+        routeId: ctx.parse(value.routeId),
+        data: ctx.parse(value.data),
+        global: ctx.parse(value.global),
+        _global: ctx.parse(value._global),
+      }
+    },
+    async async(value, ctx) {
+      return {
+        message: await ctx.parse(value.message),
+        routeId: await ctx.parse(value.routeId),
+        data: await ctx.parse(value.data),
+        global: await ctx.parse(value.global),
+        _global: await ctx.parse(value._global),
+      }
+    },
+    stream(value, ctx) {
+      return {
+        message: ctx.parse(value.message),
+        routeId: ctx.parse(value.routeId),
+        data: ctx.parse(value.data),
+        global: ctx.parse(value.global),
+        _global: ctx.parse(value._global),
+      }
+    },
+  },
+  serialize(node, ctx) {
+    return (
+      'Object.assign(new Error(' +
+      ctx.serialize(node.message) +
+      '),{isNotFound:true,routeId:' +
+      ctx.serialize(node.routeId) +
+      ',data:' +
+      ctx.serialize(node.data) +
+      ',global:' +
+      ctx.serialize(node.global) +
+      ',_global:' +
+      ctx.serialize(node._global) +
+      '})'
+    )
+  },
+  deserialize(node, ctx) {
+    return Object.assign(new Error(ctx.deserialize(node.message) as string), {
+      isNotFound: true,
+      routeId: ctx.deserialize(node.routeId),
+      data: ctx.deserialize(node.data),
+      global: ctx.deserialize(node.global),
+      _global: ctx.deserialize(node._global),
+    })
+  },
+})
diff --git a/packages/router-core/src/ssr/serializer/seroval-plugins.ts b/packages/router-core/src/ssr/serializer/seroval-plugins.ts
index de10d3bdc0..7df43fc048 100644
--- a/packages/router-core/src/ssr/serializer/seroval-plugins.ts
+++ b/packages/router-core/src/ssr/serializer/seroval-plugins.ts
@@ -1,9 +1,14 @@
 import { ReadableStreamPlugin } from 'seroval-plugins/web'
+import { NotFoundErrorPlugin } from './NotFoundErrorPlugin'
 import { ShallowErrorPlugin } from './ShallowErrorPlugin'
 import { RawStreamSSRPlugin } from './RawStream'
 import type { Plugin } from 'seroval'
 
 export const defaultSerovalPlugins = [
+  // NotFoundErrorPlugin must come before ShallowErrorPlugin: notFound() now
+  // returns an Error instance, and ShallowErrorPlugin would otherwise match it
+  // first and strip all custom properties (isNotFound, routeId, data, etc.).
+  NotFoundErrorPlugin as Plugin<any, any>,
   ShallowErrorPlugin as Plugin<Error, any>,
   // RawStreamSSRPlugin must come before ReadableStreamPlugin to match first
   RawStreamSSRPlugin,

View interactive diff ↗

➡️ This fix was rejected by manuel.schiller@caligano.de



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

@codspeed-hq
Copy link
Copy Markdown

codspeed-hq bot commented Mar 30, 2026

Merging this PR will not alter performance

✅ 6 untouched benchmarks


Comparing fix-notfound-comp (a8b1068) with main (2d1ec86)1

Open in CodSpeed

Footnotes

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

Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🧹 Nitpick comments (1)
packages/solid-router/src/not-found.tsx (1)

16-17: Use a typed cause guard instead of any casting.

Lines 16–17 bypass strict typing with as any when accessing the cause property on an unknown error object. A type guard maintains the same behavior while preserving type safety and complying with the TypeScript strict mode guideline.

Proposed refactor
+function getErrorCause(error: unknown): unknown {
+  if (typeof error === 'object' && error !== null && 'cause' in error) {
+    return (error as { cause?: unknown }).cause
+  }
+  return undefined
+}
+
 export function getNotFound(
   error: unknown,
 ): (NotFoundError & { isNotFound: true }) | undefined {
   if (isNotFound(error)) {
     return error as NotFoundError & { isNotFound: true }
   }
 
-  if (isNotFound((error as any)?.cause)) {
-    return (error as any).cause as NotFoundError & { isNotFound: true }
+  const cause = getErrorCause(error)
+  if (isNotFound(cause)) {
+    return cause as NotFoundError & { isNotFound: true }
   }
 
   return undefined
 }
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@packages/solid-router/src/not-found.tsx` around lines 16 - 17, The code uses
`as any` to access `cause` on an unknown `error`; replace this with a proper
type guard so we don't bypass strict typing. Add a small guard like `function
hasCause(e: unknown): e is { cause: unknown }` (or update `isNotFound` to accept
`unknown` and act as a type predicate for `NotFoundError & { isNotFound: true
}`), then change the branch to `if (hasCause(error) && isNotFound(error.cause))
return error.cause` (no `as any`), ensuring `isNotFound` is a type predicate so
the returned value is correctly typed as `NotFoundError & { isNotFound: true }`.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@packages/solid-router/src/not-found.tsx`:
- Around line 37-40: The onCatch callback type must match the actual value
passed from getNotFound; update the component's prop type for onCatch to accept
NotFoundError (or Error | NotFoundError if you prefer a broader contract)
instead of (error: Error) => void, adjust any related type alias/props interface
where onCatch is declared, and then remove the unsafe "as any" cast in the
props.onCatch invocation where getNotFound is called (referencing getNotFound,
NotFoundError, and props.onCatch to locate the changes).

---

Nitpick comments:
In `@packages/solid-router/src/not-found.tsx`:
- Around line 16-17: The code uses `as any` to access `cause` on an unknown
`error`; replace this with a proper type guard so we don't bypass strict typing.
Add a small guard like `function hasCause(e: unknown): e is { cause: unknown }`
(or update `isNotFound` to accept `unknown` and act as a type predicate for
`NotFoundError & { isNotFound: true }`), then change the branch to `if
(hasCause(error) && isNotFound(error.cause)) return error.cause` (no `as any`),
ensuring `isNotFound` is a type predicate so the returned value is correctly
typed as `NotFoundError & { isNotFound: true }`.
🪄 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: 3f6ec326-de3b-441d-9e8c-7b862d491fc6

📥 Commits

Reviewing files that changed from the base of the PR and between 269a34e and f07ccba.

📒 Files selected for processing (8)
  • .changeset/funny-doors-smile.md
  • packages/react-router/src/Match.tsx
  • packages/react-router/tests/not-found.test.tsx
  • packages/solid-router/src/Match.tsx
  • packages/solid-router/src/not-found.tsx
  • packages/solid-router/tests/not-found.test.tsx
  • packages/vue-router/src/Match.tsx
  • packages/vue-router/tests/not-found.test.tsx
✅ Files skipped from review due to trivial changes (3)
  • .changeset/funny-doors-smile.md
  • packages/vue-router/tests/not-found.test.tsx
  • packages/solid-router/tests/not-found.test.tsx
🚧 Files skipped from review as they are similar to previous changes (4)
  • packages/react-router/src/Match.tsx
  • packages/vue-router/src/Match.tsx
  • packages/react-router/tests/not-found.test.tsx
  • packages/solid-router/src/Match.tsx

@schiller-manuel schiller-manuel merged commit 796406d into main Mar 30, 2026
11 of 14 checks passed
@schiller-manuel schiller-manuel deleted the fix-notfound-comp branch March 30, 2026 23:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant