From daceeaa24c044dcffec038bc2ce6c0d4fedb4664 Mon Sep 17 00:00:00 2001
From: Vignesh Natarajan <vigneshnatarajan92@gmail.com>
Date: Tue, 20 Jan 2026 17:58:21 -0800
Subject: [PATCH] fix(gateway): clarify schema validation errors

Improve validation error formatting for strict schemas.
In particular, additionalProperties errors now surface the
unexpected property name and where it occurred, which makes
handshake/connect failures easier to debug.
---
 src/gateway/protocol/index.ts | 26 +++++++++++++++++++++++++-
 1 file changed, 25 insertions(+), 1 deletion(-)

diff --git a/src/gateway/protocol/index.ts b/src/gateway/protocol/index.ts
index 06847f2c5..7d82e0ecc 100644
--- a/src/gateway/protocol/index.ts
+++ b/src/gateway/protocol/index.ts
@@ -311,7 +311,31 @@ export const validateWebLoginWaitParams = ajv.compile<WebLoginWaitParams>(WebLog
 
 export function formatValidationErrors(errors: ErrorObject[] | null | undefined) {
   if (!errors) return "unknown validation error";
-  return ajv.errorsText(errors, { separator: "; " });
+
+  const parts: string[] = [];
+
+  for (const err of errors) {
+    const keyword = typeof err?.keyword === "string" ? err.keyword : "";
+    const instancePath = typeof err?.instancePath === "string" ? err.instancePath : "";
+
+    if (keyword === "additionalProperties") {
+      const params = err?.params as { additionalProperty?: unknown } | undefined;
+      const additionalProperty = params?.additionalProperty;
+      if (typeof additionalProperty === "string" && additionalProperty.trim()) {
+        const where = instancePath ? `at ${instancePath}` : "at root";
+        parts.push(`${where}: unexpected property '${additionalProperty}'`);
+        continue;
+      }
+    }
+
+    const message = typeof err?.message === "string" ? err.message : "validation error";
+    const where = instancePath ? `at ${instancePath}: ` : "";
+    parts.push(`${where}${message}`);
+  }
+
+  // De-dupe while preserving order.
+  const unique = Array.from(new Set(parts));
+  return unique.join("; ");
 }
 
 export {