Skip to content

Build and run agents you can see, understand and trust.

fix(webui): add a route-level error boundary with a friendly error page (#1828)

Xinmin Zeng829498b0bb26
diff --git a/examples/web_ui/frontend/src/App.tsx b/examples/web_ui/frontend/src/App.tsx
index 07a901459..85f40da53 100644
--- a/examples/web_ui/frontend/src/App.tsx
+++ b/examples/web_ui/frontend/src/App.tsx
@@ -3,6 +3,7 @@ import { useMemo, useState } from 'react';
import { createBrowserRouter, Navigate, RouterProvider, useNavigate } from 'react-router-dom';
import { Toaster } from 'sonner';
+import { RouteError } from '@/components/error/RouteError';
import { AppLayout } from '@/components/layout/AppLayout';
import { buildChatTour } from '@/components/tour/chatTourSteps';
import { TourCard } from '@/components/tour/TourCard';
@@ -27,17 +28,27 @@ function SetupPageRoute() {
const router = createBrowserRouter([
{
element: <AppLayout />,
+ errorElement: <RouteError />,
children: [
- { path: '/', element: <Navigate to="/chat" replace /> },
{
- path: '/chat/:agentId?/:sessionId?/:memberId?',
- element: <ChatPage />,
+ // Content-level boundary: a crash in a page replaces only
+ // the Outlet area, so AppLayout (the icon rail / nav) stays
+ // usable. The parent route keeps its own errorElement as a
+ // last-resort catch-all for AppLayout/AppSidebar crashes.
+ errorElement: <RouteError />,
+ children: [
+ { path: '/', element: <Navigate to="/chat" replace /> },
+ {
+ path: '/chat/:agentId?/:sessionId?/:memberId?',
+ element: <ChatPage />,
+ },
+ { path: '/schedule', element: <SchedulePage /> },
+ { path: '/credential', element: <CredentialPage /> },
+ ],
},
- { path: '/schedule', element: <SchedulePage /> },
- { path: '/credential', element: <CredentialPage /> },
],
},
- { path: '/setup', element: <SetupPageRoute /> },
+ { path: '/setup', element: <SetupPageRoute />, errorElement: <RouteError /> },
]);
function App() {
diff --git a/examples/web_ui/frontend/src/components/error/RouteError.tsx b/examples/web_ui/frontend/src/components/error/RouteError.tsx
new file mode 100644
index 000000000..8dcf06892
--- /dev/null
+++ b/examples/web_ui/frontend/src/components/error/RouteError.tsx
@@ -0,0 +1,58 @@
+import { useEffect } from 'react';
+import { isRouteErrorResponse, useNavigate, useRouteError } from 'react-router-dom';
+
+import { Button } from '@/components/ui/button';
+import { useTranslation } from '@/i18n/useI18n';
+
+/**
+ * Reduce an unknown route error to a one-line, human-readable detail.
+ * Returns `null` when there is nothing meaningful to show (e.g. a
+ * nullish throw or a plain object), so the caller can hide the detail
+ * box instead of rendering "null" / "[object Object]".
+ */
+function formatErrorDetail(error: unknown): string | null {
+ if (isRouteErrorResponse(error)) return `${error.status} ${error.statusText}`;
+ if (error instanceof Error) return error.message || null;
+ if (typeof error === 'string') return error || null;
+ if (typeof error === 'number' || typeof error === 'boolean') return String(error);
+ return null;
+}
+
+/**
+ * Route-level error boundary. React Router renders this in place of the
+ * crashed route element instead of its bare developer overlay, so end
+ * users get a friendly, localized message plus recovery actions (retry /
+ * go home) rather than a raw stack trace. The full error (with stack) is
+ * still logged to the console for developers.
+ */
+export function RouteError() {
+ const error = useRouteError();
+ const navigate = useNavigate();
+ const { t } = useTranslation();
+
+ useEffect(() => {
+ console.error(error);
+ }, [error]);
+
+ const detail = formatErrorDetail(error);
+
+ return (
+ <div className="flex h-full w-full flex-col items-center justify-center gap-4 p-8 text-center">
+ <div role="alert" className="flex flex-col gap-1">
+ <h1 className="text-lg font-semibold">{t('common.error')}</h1>
+ <p className="text-muted-foreground text-sm">{t('error.description')}</p>
+ </div>
+ {detail && (
+ <pre className="text-muted-foreground bg-muted max-w-md overflow-auto rounded-md p-3 text-left text-xs whitespace-pre-wrap">
+ {detail}
+ </pre>
+ )}
+ <div className="flex gap-2">
+ <Button variant="outline" onClick={() => navigate(0)}>
+ {t('error.retry')}
+ </Button>
+ <Button onClick={() => navigate('/')}>{t('error.home')}</Button>
+ </div>
+ </div>
+ );
+}
diff --git a/examples/web_ui/frontend/src/i18n/locales/en.json b/examples/web_ui/frontend/src/i18n/locales/en.json
index 2dab8c40b..c5bfe0b7d 100644
--- a/examples/web_ui/frontend/src/i18n/locales/en.json
+++ b/examples/web_ui/frontend/src/i18n/locales/en.json
@@ -41,6 +41,11 @@
"deleteTitle": "Delete {{entity}} \"{{name}}\"?",
"deleteDescription": "This action cannot be undone."
},
+ "error": {
+ "description": "The page hit an unexpected error. You can retry or go back home.",
+ "retry": "Retry",
+ "home": "Back to home"
+ },
"tool": {
"moreLines": "... {{count}} more lines",
"read": {
diff --git a/examples/web_ui/frontend/src/i18n/locales/zh.json b/examples/web_ui/frontend/src/i18n/locales/zh.json
index 5b7986045..0096f8935 100644
--- a/examples/web_ui/frontend/src/i18n/locales/zh.json
+++ b/examples/web_ui/frontend/src/i18n/locales/zh.json
@@ -41,6 +41,11 @@
"deleteTitle": "删除{{entity}} \"{{name}}\"?",
"deleteDescription": "此操作无法撤销。"
},
+ "error": {
+ "description": "页面遇到意外错误。你可以重试或返回首页。",
+ "retry": "重试",
+ "home": "返回首页"
+ },
"tool": {
"moreLines": "... 还有 {{count}} 行",
"read": {