fix(ui): surface ClickHouse error message providing a bit of advice to the user.

sumerman · sumerman · commit b39813ba45bd · 2025-09-19T00:32:23.000+02:00
diff --git a/packages/shared/src/server/repositories/clickhouse.ts b/packages/shared/src/server/repositories/clickhouse.ts
@@ -18,7 +18,6 @@ import {
 
 /**
  * Custom error class for ClickHouse resource-related errors
- * Provides actionable advice for users
  */
 // Error type configuration map
 const ERROR_TYPE_CONFIG: Record<
@@ -38,22 +37,21 @@ const ERROR_TYPE_CONFIG: Record<
   },
 };
 
-const ERROR_ADVICE_MESSAGE = [
-  "Database resource limit exceeded. Please use more specific filters or a shorter time range. We are continuously improving our API performance.",
-  "See https://langfuse.com/docs/api-and-data-platform/features/public-api for more details.",
-].join("\n");
-
 type ErrorType = keyof typeof ERROR_TYPE_CONFIG;
 
 export class ClickHouseResourceError extends Error {
+  static ERROR_ADVICE_MESSAGE = [
+    "Database resource limit exceeded.",
+    "Please use more specific filters or a shorter time range.",
+    "We are continuously improving our API performance.",
+  ].join(" ");
+
   public readonly errorType: ErrorType;
-  public readonly displayMessage: string;
 
   constructor(errType: ErrorType, originalError: Error) {
     super(originalError.message, { cause: originalError });
     this.name = "ClickHouseResourceError";
     this.errorType = errType;
-    this.displayMessage = ERROR_ADVICE_MESSAGE;
     // Preserve the original stack trace if available
     if (originalError.stack) {
       this.stack = originalError.stack;
diff --git a/web/src/__tests__/async/repositories/clickhouse-resource-errors.servertest.ts b/web/src/__tests__/async/repositories/clickhouse-resource-errors.servertest.ts
@@ -5,9 +5,6 @@ import {
 } from "@langfuse/shared/src/server";
 import { fail } from "assert";
 
-const ERROR_ADVICE_PART =
-  " Please use more specific filters or a shorter time range.";
-
 describe("ClickHouse Resource Error Handling", () => {
   describe("queryClickhouse", () => {
     describe("Error transformation with throwIf", () => {
@@ -21,7 +18,6 @@ describe("ClickHouse Resource Error Handling", () => {
         } catch (error: any) {
           expect(error).toBeInstanceOf(ClickHouseResourceError);
           expect(error.errorType).toBe("MEMORY_LIMIT");
-          expect(error.displayMessage).toContain(ERROR_ADVICE_PART);
         }
       });
 
@@ -35,7 +31,6 @@ describe("ClickHouse Resource Error Handling", () => {
         } catch (error: any) {
           expect(error).toBeInstanceOf(ClickHouseResourceError);
           expect(error.errorType).toBe("OVERCOMMIT");
-          expect(error.displayMessage).toContain(ERROR_ADVICE_PART);
         }
       });
 
@@ -49,7 +44,6 @@ describe("ClickHouse Resource Error Handling", () => {
         } catch (error: any) {
           expect(error).toBeInstanceOf(ClickHouseResourceError);
           expect(error.errorType).toBe("TIMEOUT");
-          expect(error.displayMessage).toContain(ERROR_ADVICE_PART);
         }
       });
 
@@ -185,8 +179,6 @@ describe("ClickHouse Resource Error Handling", () => {
           const resourceError = wrappedError as ClickHouseResourceError;
           if (shouldBeResourceError && errorType) {
             expect(resourceError.errorType).toBe(errorType);
-            expect(resourceError.displayMessage).toBeDefined();
-            expect(resourceError.displayMessage.length).toBeGreaterThan(0);
           }
         });
       },
diff --git a/web/src/__tests__/withMiddlewares.servertest.ts b/web/src/__tests__/withMiddlewares.servertest.ts
@@ -202,18 +202,11 @@ describe("withMiddlewares error handling", () => {
 
       await handler(req, res);
 
-      expect(res._getStatusCode()).toBe(400);
+      expect(res._getStatusCode()).toBe(524);
       const jsonData = JSON.parse(res._getData());
-      expect(jsonData).toMatchObject({
-        message: resourceError.displayMessage,
-        error: "Too much data requested",
-      });
-
-      expect(logger.error).toHaveBeenCalledWith(
-        "ClickHouse resource limit exceeded",
-        expect.objectContaining({
-          errorType: "MEMORY_LIMIT",
-        }),
+      expect(jsonData["message"]).toBeDefined();
+      expect(jsonData["message"]).toContain(
+        ClickHouseResourceError.ERROR_ADVICE_MESSAGE,
       );
     });
   });
diff --git a/web/src/features/public-api/server/withMiddlewares.ts b/web/src/features/public-api/server/withMiddlewares.ts
@@ -29,6 +29,11 @@ const defaultHandler = () => {
   throw new MethodNotAllowedError();
 };
 
+const CH_ERROR_ADVICE_FULL = [
+  ClickHouseResourceError.ERROR_ADVICE_MESSAGE,
+  "See https://langfuse.com/docs/api-and-data-platform/features/public-api for more details.",
+].join("\n");
+
 export function withMiddlewares(handlers: Handlers) {
   return async (req: NextApiRequest, res: NextApiResponse) => {
     const ctx = contextWithLangfuseProps({
@@ -80,13 +85,13 @@ export function withMiddlewares(handlers: Handlers) {
 
           logger.error("ClickHouse resource limit exceeded", {
             errorType: resourceError.errorType,
-            originalMessage: error.message,
-            displayMessage: resourceError.displayMessage,
+            message: resourceError.message,
+            suggestion: CH_ERROR_ADVICE_FULL,
           });
 
-          return res.status(400).json({
-            message: resourceError.displayMessage,
-            error: "Too much data requested",
+          return res.status(524).json({
+            message: CH_ERROR_ADVICE_FULL,
+            error: "Request is taking too long to process.",
           });
         }
 
diff --git a/web/src/server/api/trpc.ts b/web/src/server/api/trpc.ts
@@ -87,6 +87,7 @@ import {
   logger,
   addUserToSpan,
   contextWithLangfuseProps,
+  ClickHouseResourceError,
 } from "@langfuse/shared/src/server";
 
 import { AdminApiAuthService } from "@/src/ee/features/admin-api/server/adminApiAuth";
@@ -138,17 +139,26 @@ const withErrorHandling = t.middleware(async ({ ctx, next }) => {
       );
     }
 
-    // Throw a new TRPC error with:
-    // - The same error code as the original error
-    // - Either the original error message OR "Internal error" if it's an INTERNAL_SERVER_ERROR
-    res.error = new TRPCError({
-      code: res.error.code,
-      cause: null, // do not expose stack traces
-      message:
-        res.error.code !== "INTERNAL_SERVER_ERROR"
-          ? res.error.message
-          : "Internal error",
-    });
+    if (res.error.cause instanceof ClickHouseResourceError) {
+      // Surface ClickHouse errors using an advice message
+      // which is supposed to provide a bit of guidance to the user.
+      res.error = new TRPCError({
+        code: "TIMEOUT",
+        message: ClickHouseResourceError.ERROR_ADVICE_MESSAGE,
+      });
+    } else {
+      // Throw a new TRPC error with:
+      // - The same error code as the original error
+      // - Either the original error message OR "Internal error" if it's an INTERNAL_SERVER_ERROR
+      res.error = new TRPCError({
+        code: res.error.code,
+        cause: null, // do not expose stack traces
+        message:
+          res.error.code !== "INTERNAL_SERVER_ERROR"
+            ? res.error.message
+            : "Internal error",
+      });
+    }
   }
 
   return res;
