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

Đang mở
#8,843 1 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

@Rohan-Dedhia đang làm issue này rồi.

Từ ngày 5/11/2026.

  • #8881 của @Rohan-Dedhia — đang mở

Đánh giá

Độ khó
3/5
Thời gian dự kiến
Nửa ngày
Mức phù hợp với người mới
58/100
Loại issue
Lỗi
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
react, typescript
Lĩnh vực
frontend

Hướng nghiên cứu

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.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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

Ngôn ngữ chính
TypeScript
Star
15.3k
Fork
1.9k
Merge trung bình
1 ngày 5 giờ
Pull request đã merge (30 ngày)
46

Chuẩn bị môi trường

Mở trong Codespaces

Khởi chạy dev container của dự án ngay trên trình duyệt, bằng tài khoản GitHub của bạn.

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của TanStack/router

Tất cả issue của TanStack/router

Issue tương tự

Thêm issue về TypeScript

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.