react-router: hydrating an SSR-errored match throws (React error #520); `MatchInner` renders the error component on the server but `throw`s on the client

未关闭
#8,843 1 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 1 天内回复

@Rohan-Dedhia 已经在做这个了。

开始于 2026年11月5日。

  • #8881 来自 @Rohan-Dedhia —— 未关闭

评估

难度
3/5
预计耗时
半天
新手友好度
58/100
Issue 类型
缺陷
描述清晰度
描述清楚
活跃度
活跃
技术栈
react, typescript
领域
frontend

调研方向

The bug is in the status === 'error' branch of MatchInner in packages/react-router/src/Match.tsx, where the server renders the error component but the client throws match.error. Reproduce with the SSR-then-hydrate script in the issue, using jsdom, and watch for the recoverable error and console error. Done when hydrating the server HTML reports no recoverable error, the error component stays rendered, and router.invalidate() still re-runs the loader. Confirm the reset behaviour with a maintainer before opening a pull request.

由索引模型根据 Issue 内容生成。

描述

Versions

  • @tanstack/react-router 1.170.41 and 1.170.46 (identical code in Match.js / Match.cjs)
  • @tanstack/router-core 1.171.34
  • react / react-dom 19.3.0

Summary

When a route loader throws during SSR and the route has an errorComponent (or the router has a defaultErrorComponent), the server renders the error component directly. On the client, MatchInner does throw match.error for the same errored match instead of rendering the error component, so hydration of the server-rendered error UI throws. React recovers by client-rendering the whole root and reports the failure through onRecoverableError as minified error #520 ("There was an error during concurrent rendering but React was able to recover by instead synchronously rendering the entire root."), with the route error as its cause. The throw also reaches the route's CatchBoundary, so React's default onCaughtError logs the route error to the console.

The server branch and the client branch of the same if (match.status === "error") block disagree about what an errored match renders. Server-rendered HTML for an errored match is therefore never hydratable without a recoverable error.

Minimal repro

import { createRootRoute, createRoute, createRouter, Outlet } from "@tanstack/react-router";
import { RouterServer, renderRouterToString } from "@tanstack/react-router/ssr/server";
import { RouterClient } from "@tanstack/react-router/ssr/client";
import { createRequestHandler } from "@tanstack/router-core/ssr/server";
import { hydrateRoot } from "react-dom/client";

const rootRoute = createRootRoute({ component: Outlet });
const indexRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: "/",
  loader: () => {
    throw new Error("loader failed");
  },
  errorComponent: ({ error }) => <p role="alert">Failed: {error.message}</p>,
  component: () => <p>ok</p>,
});
const routeTree = rootRoute.addChildren([indexRoute]);
const makeRouter = () => createRouter({ routeTree });

// 1. Server: the loader throws, the errorComponent is rendered into the HTML.
const response = await createRequestHandler({
  request: new Request("http://localhost/"),
  createRouter: makeRouter,
})(({ request, router, responseHeaders }) =>
  renderRouterToString({
    request,
    router,
    responseHeaders,
    children: <RouterServer router={router} />,
  }),
);
const html = await response.text();

// 2. Client (jsdom or a browser): load `html` as the document, then hydrate.
const recoverable: unknown[] = [];
hydrateRoot(document, <RouterClient router={makeRouter()} />, {
  onRecoverableError: (error) => recoverable.push(error),
});

Observed

  • recoverable is [Error("There was an error during concurrent rendering but React was able to recover by instead synchronously rendering the entire root.")] with cause set to the dehydrated route error.
  • The error is thrown from MatchInner in Match.js: throw match.error; (the status === "error" branch, client side).
  • React's default onCaughtError also console.errors the route error from the route CatchBoundary.

Expected

Hydrating an errored match renders the same error component the server rendered and does not throw, so there is no recoverable error and no console error. router.invalidate() (or the boundary reset) still re-runs the loader.

Root cause

packages/react-router/src/Match.tsx, MatchInner:

if (match.status === 'error') {
  if (isServer ?? router.isServer) {
    const RouteErrorComponent =
      (route.options.errorComponent ?? router.options.defaultErrorComponent) || ErrorComponent
    return (
      <RouteErrorComponent error={match.error} reset={undefined} info={{ componentStack: '' }} />
    )
  }
  throw match.error
}

The client path relies on CatchBoundary (only present when the route has an errorComponent) to render the error. For a match whose error was produced on the server and dehydrated, the throw happens while hydrating markup that already contains the error UI.

Proposed fix (patch we apply with pnpm patch)

Render the error component on the client as well, with a reset that invalidates the errored match and the same info as the server branch:

diff --git a/dist/cjs/Match.cjs b/dist/cjs/Match.cjs
index 0062da5e06271f1e25545979aa137b37e30ee295..0f13eb1cdd6bbdca38f2bbe9d348f91b4c694ddf 100644
--- a/dist/cjs/Match.cjs
+++ b/dist/cjs/Match.cjs
@@ -115,15 +115,14 @@ var MatchInner = react.memo(function MatchInnerImpl({ match }) {
 	}
 	if (match.status === "notFound") return require_renderRouteNotFound.renderRouteNotFound(router, route, match.error);
 	if (match.status === "error") {
-		if (_tanstack_router_core_isServer.isServer ?? router.isServer) {
-			const errorElement = /* @__PURE__ */ (0, react_jsx_runtime.jsx)((route.options.errorComponent ?? router.options.defaultErrorComponent) || require_CatchBoundary.ErrorComponent, {
-				error: match.error,
-				reset: void 0,
-				info: { componentStack: "" }
-			});
-			return process.env.NODE_ENV !== "production" ? require_nonRouteComponentContext.wrapInNonRouteComponentContext(errorElement, "errorComponent") : errorElement;
-		}
-		throw match.error;
+		const errorElement = /* @__PURE__ */ (0, react_jsx_runtime.jsx)((route.options.errorComponent ?? router.options.defaultErrorComponent) || require_CatchBoundary.ErrorComponent, {
+			error: match.error,
+			reset: _tanstack_router_core_isServer.isServer ?? router.isServer ? void 0 : () => {
+				router.invalidate({ filter: (d) => d.id === match.id });
+			},
+			info: { componentStack: "" }
+		});
+		return process.env.NODE_ENV !== "production" ? require_nonRouteComponentContext.wrapInNonRouteComponentContext(errorElement, "errorComponent") : errorElement;
 	}
 	return out;
 });
diff --git a/dist/esm/Match.js b/dist/esm/Match.js
index e275c3cb8c552f8adc91d18eecf28cad2412d117..4347395af384854fa048fd51fdd8098c8a959fbf 100644
--- a/dist/esm/Match.js
+++ b/dist/esm/Match.js
@@ -113,15 +113,14 @@ var MatchInner = React$1.memo(function MatchInnerImpl({ match }) {
 	}
 	if (match.status === "notFound") return renderRouteNotFound(router, route, match.error);
 	if (match.status === "error") {
-		if (isServer ?? router.isServer) {
-			const errorElement = /* @__PURE__ */ jsx((route.options.errorComponent ?? router.options.defaultErrorComponent) || ErrorComponent, {
-				error: match.error,
-				reset: void 0,
-				info: { componentStack: "" }
-			});
-			return process.env.NODE_ENV !== "production" ? wrapInNonRouteComponentContext(errorElement, "errorComponent") : errorElement;
-		}
-		throw match.error;
+		const errorElement = /* @__PURE__ */ jsx((route.options.errorComponent ?? router.options.defaultErrorComponent) || ErrorComponent, {
+			error: match.error,
+			reset: isServer ?? router.isServer ? void 0 : () => {
+				router.invalidate({ filter: (d) => d.id === match.id });
+			},
+			info: { componentStack: "" }
+		});
+		return process.env.NODE_ENV !== "production" ? wrapInNonRouteComponentContext(errorElement, "errorComponent") : errorElement;
 	}
 	return out;
 });

(The unified diff above is against the built dist/esm/Match.js and dist/cjs/Match.cjs; the equivalent source change is in MatchInner in src/Match.tsx: drop the throw match.error, build the element unconditionally, and pass reset: isServer ?? router.isServer ? undefined : () => router.invalidate({ filter: (d) => d.id === match.id }).)

Notes

  • The repro is distilled from a vitest + jsdom harness that does an SSR render, loads the HTML as the document, and calls hydrateRoot; it has the same shape as a production Hono SSR server plus a browser entry. Adjust the render helper (renderRouterToStream, renderRouterToString) to your setup.
  • With the patch the same harness reports no recoverable errors, no console errors, the error component is present after hydration, and a Retry button wired to router.invalidate() clears the error and re-runs the loader.

Related: #8241 (the same server-inline / client-throw split in @tanstack/solid-router).

主要语言
TypeScript
星标
15.3k
派生
1.9k
平均合并
1 天 5 小时
30 天内合并 PR
46

环境准备

在 Codespaces 中打开

在浏览器里用你自己的 GitHub 账号启动这个项目的开发容器。

从这里开始

  1. 先读完整个 Issue,再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库,在一个分支上完成修改。
  4. 提交 Pull Request,并在描述里引用这个 Issue 编号。

TanStack/router 的其他 Issue

查看 TanStack/router 的全部 Issue

相似的 Issue

更多 TypeScript Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。