fix(dashboard): stop model-test error freezing the page (React #31 object toast) (#6161)

Clicking 'test' on a provider model (e.g. a ClinePass flash model) could freeze
the entire dashboard. Root cause: POST /api/models/test returned an OBJECT in
`error` on the Zod-validation and invalid-JSON paths (`validation.error.format()`
/ a details object). The client does `notify.error(data.error)`, and
NotificationToast renders the message directly as a React child — an object throws
React #31 ('Objects are not valid as a React child'), crashing the tree = frozen
page instead of a toast.

Fixed in three layers (defense in depth):
1. Server (root cause): /api/models/test now returns a STRING `error` on every
   path — flattens Zod issues to text, returns 'Invalid JSON body' for bad JSON.
2. Client: onTestModel funnels the response through extractApiErrorMessage() so any
   object-shaped error is coerced to a string before notify.error.
3. Toast: NotificationToast coerces title/message via toToastText() — a resilient
   catch-all so no future caller can freeze the page with a non-string.

Tests (Rule #18, both node:test / blocking suite):
- tests/unit/models-test-error-shape.test.ts — asserts STRING error on Zod-fail,
  missing-field, and invalid-JSON (fails on the pre-fix route: 3/3 red -> green).
- tests/unit/notification-toast-coercion.test.ts — toToastText coercion matrix.

src/app/(dashboard)/dashboard/providers/[id]/hooks/useModelVisibilityHandlers.ts

@@ -31,6 +31,7 @@ import {
   type CompatByProtocolMap,
 } from "../providerPageHelpers";
 import { useNotificationStore } from "@/store/notificationStore";
+import { extractApiErrorMessage } from "@/shared/http/apiErrorMessage";
 
 type NotifyStore = ReturnType<typeof useNotificationStore>;
 
@@ -312,7 +313,10 @@ export function useModelVisibilityHandlers({
         );
         setModelTestStatus((prev) => ({ ...prev, [modelId]: "ok" }));
       } else {
-        notify.error(data.error || "Model test failed");
+        // extractApiErrorMessage coerces any object-shaped `error` (e.g. a Zod
+        // format object) to a string so notify.error never hands the toast a
+        // non-string child (React #31 → frozen page).
+        notify.error(extractApiErrorMessage(data, "Model test failed"));
         setModelTestStatus((prev) => ({ ...prev, [modelId]: "error" }));
       }
     } catch (err) {

src/app/api/models/test/route.ts

@@ -20,21 +20,23 @@ export async function POST(request: Request) {
   try {
     rawBody = await request.json();
   } catch {
-    return NextResponse.json(
-      {
-        error: {
-          message: "Invalid request",
-          details: [{ field: "body", message: "Invalid JSON body" }],
-        },
-      },
-      { status: 400 }
-    );
+    // Keep `error` a plain string — the dashboard renders it directly in a toast,
+    // and an object here throws React #31 ("Objects are not valid as a React
+    // child"), freezing the whole page instead of showing the message.
+    return NextResponse.json({ status: "error", error: "Invalid JSON body" }, { status: 400 });
   }
 
   try {
     const validation = testModelSchema.safeParse(rawBody);
     if (!validation.success) {
-      return NextResponse.json({ error: validation.error.format() }, { status: 400 });
+      // Flatten the Zod issues to a string (never return the object — see above).
+      const detail = validation.error.issues
+        .map((i) => `${i.path.join(".") || "body"}: ${i.message}`)
+        .join("; ");
+      return NextResponse.json(
+        { status: "error", error: `Invalid request: ${detail}` },
+        { status: 400 }
+      );
     }
     const { providerId, modelId, connectionId } = validation.data;
 

src/shared/components/NotificationToast.tsx

@@ -19,6 +19,28 @@ const ICONS = {
   info: "ℹ",
 };
 
+/**
+ * Coerce a toast title/message to a string. `message`/`title` are typed as
+ * `string`, but callers occasionally pass a raw API error body (an object) —
+ * rendering that object directly throws React #31 ("Objects are not valid as a
+ * React child") and freezes the whole page. This keeps the toast resilient no
+ * matter what a caller hands it.
+ */
+export function toToastText(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (value == null) return "";
+  if (typeof value === "object") {
+    const message = (value as { message?: unknown }).message;
+    if (typeof message === "string") return message;
+    try {
+      return JSON.stringify(value);
+    } catch {
+      return String(value);
+    }
+  }
+  return String(value);
+}
+
 const BG_DARK = "rgba(30, 30, 30, 0.95)";
 
 const COLORS = {
@@ -101,7 +123,7 @@ function Toast({ notification, onDismiss }) {
               marginBottom: "2px",
             }}
           >
-            {notification.title}
+            {toToastText(notification.title)}
           </div>
         )}
         <div
@@ -111,7 +133,7 @@ function Toast({ notification, onDismiss }) {
             lineHeight: 1.4,
           }}
         >
-          {notification.message}
+          {toToastText(notification.message)}
         </div>
       </div>
       {notification.dismissible && (

tests/unit/models-test-error-shape.test.ts

@@ -0,0 +1,65 @@
+// Regression guard: POST /api/models/test must always return a STRING `error`,
+// never an object. The Zod-validation and invalid-JSON paths used to return
+// `{ error: <object> }` (Zod .format() / a details object). The dashboard renders
+// that value directly in a toast, so an object froze the whole page (React #31).
+// The "test a model → screen froze" bug.
+//
+// DB handles released in test.after (CLAUDE.md learning: unreleased SQLite
+// handles hang node:test).
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const TEST_DATA_DIR = fs.mkdtempSync(path.join(os.tmpdir(), "omniroute-models-test-"));
+process.env.DATA_DIR = TEST_DATA_DIR;
+
+const core = await import("../../src/lib/db/core.ts");
+const settingsDb = await import("../../src/lib/db/settings.ts");
+const route = await import("../../src/app/api/models/test/route.ts");
+
+test.before(async () => {
+  await settingsDb.updateSettings({ requireLogin: false });
+});
+
+test.after(async () => {
+  core.resetDbInstance();
+  fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true });
+});
+
+function post(body: unknown, rawText?: string) {
+  return route.POST(
+    new Request("http://localhost:20128/api/models/test", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: rawText !== undefined ? rawText : JSON.stringify(body),
+    })
+  );
+}
+
+test("Zod validation failure returns a STRING error (not an object)", async () => {
+  // connectionId "" fails z.string().min(1).optional() -> validation error path
+  const res = await post({ providerId: "openai", modelId: "gpt-4o", connectionId: "" });
+  assert.equal(res.status, 400);
+  const body = await res.json();
+  assert.equal(typeof body.error, "string", "error must be a string, never an object");
+  assert.equal(body.status, "error");
+  assert.match(body.error, /Invalid request/i);
+});
+
+test("missing required field returns a STRING error", async () => {
+  const res = await post({ providerId: "openai" }); // no modelId
+  assert.equal(res.status, 400);
+  const body = await res.json();
+  assert.equal(typeof body.error, "string");
+});
+
+test("invalid JSON body returns a STRING error (not an object)", async () => {
+  const res = await post(undefined, "{ not json ");
+  assert.equal(res.status, 400);
+  const body = await res.json();
+  assert.equal(typeof body.error, "string");
+  assert.match(body.error, /Invalid JSON/i);
+});

tests/unit/notification-toast-coercion.test.ts

@@ -0,0 +1,35 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { toToastText } from "@/shared/components/NotificationToast";
+
+// Regression guard: a toast message/title that is NOT a string (e.g. a raw API
+// error body — a Zod `.format()` object) must be coerced to a string. Rendering
+// an object as a React child throws React #31 and freezes the whole page. This
+// was the "test model → screen froze" bug on the provider page.
+
+test("returns strings unchanged", () => {
+  assert.equal(toToastText("hello"), "hello");
+  assert.equal(toToastText(""), "");
+});
+
+test("returns empty string for null/undefined (never crashes render)", () => {
+  assert.equal(toToastText(null), "");
+  assert.equal(toToastText(undefined), "");
+});
+
+test("prefers a nested string .message on an object error body", () => {
+  assert.equal(toToastText({ message: "Rate limited" }), "Rate limited");
+});
+
+test("JSON-stringifies an arbitrary object instead of throwing (Zod .format() shape)", () => {
+  const zodish = { modelId: { _errors: ["Required"] }, _errors: [] };
+  const out = toToastText(zodish);
+  assert.equal(typeof out, "string");
+  assert.ok(out.includes("_errors"));
+});
+
+test("coerces numbers/booleans to string", () => {
+  assert.equal(toToastText(42), "42");
+  assert.equal(toToastText(true), "true");
+});