Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

fix(web): show readable tRPC Zod validation toasts (#16313)

Nikita Kabardin47737fd065aa
diff --git a/web/src/utils/api.clienttest.ts b/web/src/utils/api.clienttest.ts
index 4a976d1298..9da363702c 100644
--- a/web/src/utils/api.clienttest.ts
+++ b/web/src/utils/api.clienttest.ts
@@ -11,6 +11,7 @@ import {
isExpectedTrpcClientError,
isNetworkConnectivityError,
isTrpcResponseParseError,
+ isTrpcZodValidationError,
reportNonTrpcError,
reportTrpcErrorWithoutToast,
} from "@/src/utils/api";
@@ -47,6 +48,7 @@ const trpcServerError = (opts: {
httpStatus: number;
path?: string;
message?: string;
+ zodError?: unknown;
}) =>
TRPCClientError.from({
error: {
@@ -56,10 +58,23 @@ const trpcServerError = (opts: {
code: opts.code,
httpStatus: opts.httpStatus,
...(opts.path !== undefined ? { path: opts.path } : {}),
+ ...(opts.zodError !== undefined ? { zodError: opts.zodError } : {}),
},
},
});
+/** Zod 4 stringifies input failures as a JSON issue list — the toast users see today. */
+const ZOD4_TOO_SMALL_MESSAGE = JSON.stringify([
+ {
+ origin: "string",
+ code: "too_small",
+ minimum: 1,
+ inclusive: true,
+ path: ["name"],
+ message: "Too small: expected string to have >=1 characters",
+ },
+]);
+
describe("isNetworkConnectivityError", () => {
it("detects the reported failed fetch error without a response", () => {
const error = TRPCClientError.from(new TypeError("Failed to fetch"));
@@ -331,6 +346,57 @@ describe("isExpectedTrpcClientError", () => {
).toBe(false);
});
+ it("suppresses Zod input validation (empty/too-short fields) as expected user input", () => {
+ expect(
+ isExpectedTrpcClientError(
+ trpcServerError({
+ code: "BAD_REQUEST",
+ httpStatus: 400,
+ path: "prompts.create",
+ message: ZOD4_TOO_SMALL_MESSAGE,
+ }),
+ ),
+ ).toBe(true);
+ expect(
+ isExpectedTrpcClientError(
+ trpcServerError({
+ code: "BAD_REQUEST",
+ httpStatus: 400,
+ path: "traces.byId",
+ message: `Invalid input, ${ZOD4_TOO_SMALL_MESSAGE}`,
+ }),
+ ),
+ ).toBe(true);
+ expect(
+ isExpectedTrpcClientError(
+ trpcServerError({
+ code: "BAD_REQUEST",
+ httpStatus: 400,
+ path: "prompts.create",
+ message: "Invalid input",
+ zodError: {
+ formErrors: [],
+ fieldErrors: {
+ name: ["Too small: expected string to have >=1 characters"],
+ },
+ },
+ }),
+ ),
+ ).toBe(true);
+ });
+
+ it("does not treat a non-Zod BAD_REQUEST as validation", () => {
+ expect(
+ isTrpcZodValidationError(
+ trpcServerError({
+ code: "BAD_REQUEST",
+ httpStatus: 400,
+ message: "Invalid input, projectId is required",
+ }),
+ ),
+ ).toBe(false);
+ });
+
it("does not suppress an unrecognized tRPC code", () => {
const error = trpcServerError({
code: "TEAPOT",
@@ -474,6 +540,21 @@ describe("reportTrpcErrorWithoutToast", () => {
});
});
+ it("does not capture Zod input validation (empty/too-short fields)", () => {
+ reportTrpcErrorWithoutToast(
+ trpcServerError({
+ code: "BAD_REQUEST",
+ httpStatus: 400,
+ path: "prompts.create",
+ message: ZOD4_TOO_SMALL_MESSAGE,
+ }),
+ "prompts",
+ );
+
+ expect(captureExceptionMock).not.toHaveBeenCalled();
+ expect(addBreadcrumbMock).toHaveBeenCalledTimes(1);
+ });
+
// Negative fixture: real errors MUST still be captured, with the
// procedure/code fingerprint and tags.
it("captures a real (5xx) tRPC error with fingerprint and tags", () => {
diff --git a/web/src/utils/api.ts b/web/src/utils/api.ts
index 8e9f1e8ce2..e09e6678ff 100644
--- a/web/src/utils/api.ts
+++ b/web/src/utils/api.ts
@@ -29,6 +29,9 @@ import { type AppRouter } from "@/src/server/api/root";
import { reportError } from "@/src/utils/reportError";
import { setUpSuperjson } from "@/src/utils/superjson";
import { trpcErrorToast } from "@/src/utils/trpcErrorToast";
+import { isTrpcZodValidationError } from "@/src/utils/trpcValidationError";
+
+export { isTrpcZodValidationError } from "@/src/utils/trpcValidationError";
setUpSuperjson();
@@ -128,9 +131,12 @@ export const isNetworkConnectivityError = (error: unknown): boolean => {
* for each suppressed error so its path + code stay in the trail of any real
* event captured later in the session.
*
- * Deliberately narrow: only these codes on an actual `TRPCClientError`. A 5xx
- * (`INTERNAL_SERVER_ERROR`), a `BAD_REQUEST`, an unrecognized code, or any
- * non-tRPC error is not expected and keeps flowing to Sentry unchanged.
+ * Deliberately narrow: only these codes on an actual `TRPCClientError`, plus
+ * Zod input validation (`BAD_REQUEST` whose message is a Zod 4 issue list or
+ * whose `data.zodError` is populated). Empty/too-short fields are the product
+ * working as designed — the toast is the UX; Sentry must not log them.
+ * A 5xx (`INTERNAL_SERVER_ERROR`), a non-Zod `BAD_REQUEST`, an unrecognized
+ * code, or any non-tRPC error is not expected and keeps flowing to Sentry.
*/
export const EXPECTED_TRPC_ERROR_CODES = [
"NOT_FOUND",
@@ -183,10 +189,13 @@ export const getTrpcErrorFingerprint = (error: unknown): string[] => [
*/
export const isExpectedTrpcClientError = (error: unknown): boolean => {
const code = getTrpcErrorCode(error);
- return (
+ if (
code !== undefined &&
(EXPECTED_TRPC_ERROR_CODES as readonly string[]).includes(code)
- );
+ ) {
+ return true;
+ }
+ return isTrpcZodValidationError(error);
};
// HTTP statuses returned when a request's URL/headers are too large for the
diff --git a/web/src/utils/trpcErrorToast.clienttest.ts b/web/src/utils/trpcErrorToast.clienttest.ts
new file mode 100644
index 0000000000..ea4c5a9f18
--- /dev/null
+++ b/web/src/utils/trpcErrorToast.clienttest.ts
@@ -0,0 +1,146 @@
+// @vitest-environment node
+
+import { TRPCClientError } from "@trpc/client";
+import { vi } from "vitest";
+import { trpcErrorToast } from "@/src/utils/trpcErrorToast";
+import { formatTrpcZodValidationDescription } from "@/src/utils/trpcValidationError";
+
+const { showErrorToastMock } = vi.hoisted(() => ({
+ showErrorToastMock: vi.fn(),
+}));
+
+vi.mock("@/src/features/notifications/showErrorToast", () => ({
+ showErrorToast: showErrorToastMock,
+}));
+
+const ZOD4_TOO_SMALL_MESSAGE = JSON.stringify([
+ {
+ origin: "string",
+ code: "too_small",
+ minimum: 1,
+ inclusive: true,
+ path: ["name"],
+ message: "Too small: expected string to have >=1 characters",
+ },
+]);
+
+const trpcError = (opts: {
+ code: string;
+ httpStatus: number;
+ message: string;
+ path?: string;
+ zodError?: unknown;
+}) =>
+ TRPCClientError.from({
+ error: {
+ code: -32600,
+ message: opts.message,
+ data: {
+ code: opts.code,
+ httpStatus: opts.httpStatus,
+ ...(opts.path !== undefined ? { path: opts.path } : {}),
+ ...(opts.zodError !== undefined ? { zodError: opts.zodError } : {}),
+ },
+ },
+ });
+
+describe("formatTrpcZodValidationDescription", () => {
+ it("turns a Zod 4 JSON issue list into field: message lines", () => {
+ const error = trpcError({
+ code: "BAD_REQUEST",
+ httpStatus: 400,
+ message: ZOD4_TOO_SMALL_MESSAGE,
+ });
+
+ expect(formatTrpcZodValidationDescription(error)).toBe(
+ "name: Too small: expected string to have >=1 characters",
+ );
+ });
+
+ it("extracts an issue list prefixed with human text", () => {
+ const error = trpcError({
+ code: "BAD_REQUEST",
+ httpStatus: 400,
+ message: `Invalid input, ${ZOD4_TOO_SMALL_MESSAGE}`,
+ });
+
+ expect(formatTrpcZodValidationDescription(error)).toBe(
+ "name: Too small: expected string to have >=1 characters",
+ );
+ });
+
+ it("joins multiple issues and uses flattenError when the message is not JSON", () => {
+ const error = trpcError({
+ code: "BAD_REQUEST",
+ httpStatus: 400,
+ message: "Invalid input",
+ zodError: {
+ formErrors: ["Fix the form"],
+ fieldErrors: {
+ name: ["Too small: expected string to have >=1 characters"],
+ slug: ["Required"],
+ },
+ },
+ });
+
+ expect(formatTrpcZodValidationDescription(error)).toBe(
+ [
+ "name: Too small: expected string to have >=1 characters",
+ "slug: Required",
+ "Fix the form",
+ ].join("\n"),
+ );
+ });
+
+ it("returns null for a non-Zod BAD_REQUEST", () => {
+ const error = trpcError({
+ code: "BAD_REQUEST",
+ httpStatus: 400,
+ message: "Invalid input, projectId is required",
+ });
+
+ expect(formatTrpcZodValidationDescription(error)).toBeNull();
+ });
+});
+
+describe("trpcErrorToast", () => {
+ beforeEach(() => {
+ showErrorToastMock.mockClear();
+ });
+
+ it("shows a readable Invalid input toast instead of the Zod JSON dump", () => {
+ trpcErrorToast(
+ trpcError({
+ code: "BAD_REQUEST",
+ httpStatus: 400,
+ path: "prompts.create",
+ message: ZOD4_TOO_SMALL_MESSAGE,
+ }),
+ );
+
+ expect(showErrorToastMock).toHaveBeenCalledWith(
+ "Invalid input",
+ "name: Too small: expected string to have >=1 characters",
+ "WARNING",
+ "prompts.create",
+ );
+ });
+
+ it("keeps the generic Bad Request title for non-Zod 4xx errors", () => {
+ trpcErrorToast(
+ trpcError({
+ code: "BAD_REQUEST",
+ httpStatus: 400,
+ path: "prompts.create",
+ message: "Invalid input, projectId is required",
+ }),
+ );
+
+ expect(showErrorToastMock).toHaveBeenCalledWith(
+ "Bad Request",
+ "Invalid input, projectId is required",
+ "WARNING",
+ "prompts.create",
+ );
+ });
+});
diff --git a/web/src/utils/trpcErrorToast.tsx b/web/src/utils/trpcErrorToast.tsx
index ad04b1caf9..49a5387d91 100644
--- a/web/src/utils/trpcErrorToast.tsx
+++ b/web/src/utils/trpcErrorToast.tsx
@@ -1,5 +1,6 @@
import { TRPCClientError } from "@trpc/client";
import { showErrorToast } from "@/src/features/notifications/showErrorToast";
+import { formatTrpcZodValidationDescription } from "@/src/utils/trpcValidationError";
// Catch network level errors, e.g. by proxy rate-limiting
@@ -95,11 +96,13 @@ export const trpcErrorToast = (error: unknown) => {
const { errorTitle, httpStatus } = getErrorTitleAndHttpCode(error);
const path = error.data?.path;
- const description = getErrorDescription(httpStatus);
+ const validationDescription = formatTrpcZodValidationDescription(error);
+ const description =
+ validationDescription ?? error.message ?? getErrorDescription(httpStatus);
showErrorToast(
- errorTitle,
- error.message ?? description,
+ validationDescription ? "Invalid input" : errorTitle,
+ description,
httpStatus >= 500 && httpStatus < 600 ? "ERROR" : "WARNING",
path,
);
diff --git a/web/src/utils/trpcValidationError.ts b/web/src/utils/trpcValidationError.ts
new file mode 100644
index 0000000000..19d6046cd9
--- /dev/null
+++ b/web/src/utils/trpcValidationError.ts
@@ -0,0 +1,118 @@
+import { TRPCClientError } from "@trpc/client";
+
+type ZodFlattenedError = {
+ formErrors?: unknown;
+ fieldErrors?: unknown;
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+ typeof value === "object" && value !== null;
+
+const getErrorCode = (error: TRPCClientError<any>): string | undefined => {
+ const code = (error.data as { code?: unknown } | undefined)?.code;
+ return typeof code === "string" ? code : undefined;
+};
+
+const getZodError = (error: TRPCClientError<any>): ZodFlattenedError | null => {
+ const zodError = (error.data as { zodError?: unknown } | undefined)?.zodError;
+ if (!isRecord(zodError)) return null;
+ return zodError as ZodFlattenedError;
+};
+
+const formatPath = (path: unknown): string => {
+ if (!Array.isArray(path)) return "";
+ return path
+ .filter((part) => part !== undefined && part !== null && part !== "")
+ .join(".");
+};
+
+/**
+ * Zod 4's `ZodError.message` is a JSON array of issues. tRPC puts that string
+ * on `TRPCClientError.message`, which is what the global error toast shows.
+ */
+export const parseZodIssueList = (
+ message: string,
+): Array<{ path: unknown; message: string }> | null => {
+ const trimmed = message.trim();
+ // tRPC sometimes prefixes the Zod 4 JSON issue list, e.g.
+ // `Invalid input, [{ "code": "too_small", ... }]`.
+ const start = trimmed.indexOf("[");
+ if (start === -1) return null;
+
+ try {
+ const parsed: unknown = JSON.parse(trimmed.slice(start));
+ if (!Array.isArray(parsed) || parsed.length === 0) return null;
+
+ const issues: Array<{ path: unknown; message: string }> = [];
+ for (const item of parsed) {
+ if (!isRecord(item) || typeof item.message !== "string") return null;
+ issues.push({ path: item.path, message: item.message });
+ }
+ return issues;
+ } catch {
+ return null;
+ }
+};
+
+const formatFlattenedZodError = (
+ zodError: ZodFlattenedError,
+): string | null => {
+ const lines: string[] = [];
+
+ if (isRecord(zodError.fieldErrors)) {
+ for (const [field, messages] of Object.entries(zodError.fieldErrors)) {
+ if (!Array.isArray(messages)) continue;
+ for (const message of messages) {
+ if (typeof message === "string" && message.length > 0) {
+ lines.push(`${field}: ${message}`);
+ }
+ }
+ }
+ }
+
+ if (Array.isArray(zodError.formErrors)) {
+ for (const message of zodError.formErrors) {
+ if (typeof message === "string" && message.length > 0) {
+ lines.push(message);
+ }
+ }
+ }
+
+ return lines.length > 0 ? lines.join("\n") : null;
+};
+
+/**
+ * True when a tRPC client error is Zod input validation (empty / too-short /
+ * wrong-type fields), not an application bug.
+ *
+ * Matches either the Zod 4 JSON issue list on `error.message` or the flattened
+ * `data.zodError` attached by the tRPC `errorFormatter`.
+ */
+export const isTrpcZodValidationError = (error: unknown): boolean => {
+ if (!(error instanceof TRPCClientError)) return false;
+ if (getErrorCode(error) !== "BAD_REQUEST") return false;
+ if (parseZodIssueList(error.message) !== null) return true;
+
+ const zodError = getZodError(error);
+ return zodError !== null && formatFlattenedZodError(zodError) !== null;
+};
+
+/** Human-readable field messages, or null when this is not a Zod validation error. */
+export const formatTrpcZodValidationDescription = (
+ error: unknown,
+): string | null => {
+ if (!(error instanceof TRPCClientError)) return null;
+
+ const issues = parseZodIssueList(error.message);
+ if (issues) {
+ return issues
+ .map((issue) => {
+ const path = formatPath(issue.path);
+ return path.length > 0 ? `${path}: ${issue.message}` : issue.message;
+ })
+ .join("\n");
+ }
+
+ const zodError = getZodError(error);
+ return zodError ? formatFlattenedZodError(zodError) : null;
+};