fix(max): keep the real cause when an async query fails

ee/hogai/context/insight/query_executor.py

@@ -442,7 +442,12 @@ def process_query_dict_with_tags() -> dict | BaseModel:
                 if query_status.get("error"):
                     if error_message := query_status.get("error_message"):
                         raise APIException(error_message)
-                    raise Exception("Query failed")
+                    # The status hides the message text because it's not user-safe, but error_code
+                    # carries the machine-readable cause (a ClickHouse memory limit, an internal
+                    # error, a worker crash). These are transient, so retry instead of dead-ending
+                    # on an opaque "Query failed" that the report pipeline never retries.
+                    error_code = query_status.get("error_code")
+                    raise MaxToolRetryableError(f"Query failed: {error_code}" if error_code else "Query failed")
 
                 # Use the completed query results
                 response_dict = query_status["results"]
@@ -453,6 +458,7 @@ def process_query_dict_with_tags() -> dict | BaseModel:
             HogQLNotImplementedError,
             ExposedCHQueryError,
             UserAccessControlError,
+            MaxToolRetryableError,
         ) as err:
             elapsed = time.time() - start_time
             # Handle known query execution errors with user-friendly messages

ee/hogai/context/insight/test/test_query_executor.py

@@ -396,6 +396,32 @@ async def test_async_query_polling_with_error(self, mock_get_query_status, mock_
 
         self.assertIn("Query failed with error", str(context.exception))
 
+    @patch("ee.hogai.context.insight.query_executor.process_query_dict")
+    @patch("ee.hogai.context.insight.query_executor.get_query_status")
+    async def test_async_query_polling_error_without_message_is_retryable(
+        self, mock_get_query_status, mock_process_query
+    ):
+        # A non-user-safe failure hides the message text but carries error_code. The step must retry
+        # (MaxToolRetryableError) and surface the cause, not dead-end on an opaque "Query failed".
+        mock_process_query.return_value = {"query_status": {"id": "test-query-id", "complete": False}}
+        mock_get_query_status.return_value = Mock(
+            model_dump=lambda mode: {
+                "id": "test-query-id",
+                "complete": True,
+                "error": True,
+                "error_message": None,
+                "error_code": "CHQueryErrorMemoryLimitExceeded",
+            }
+        )
+
+        query = AssistantTrendsQuery(series=[])
+
+        with patch("ee.hogai.context.insight.query_executor.asyncio.sleep"):
+            with self.assertRaises(MaxToolRetryableError) as context:
+                await self.query_runner.arun_and_format_query(query)
+
+        self.assertIn("CHQueryErrorMemoryLimitExceeded", str(context.exception))
+
     @override_settings(TEST=False)
     @patch("ee.hogai.context.insight.query_executor.process_query_dict")
     async def test_execution_mode_in_production(self, mock_process_query):

posthog/clickhouse/client/execute_async.py

@@ -20,7 +20,7 @@
 from posthog.clickhouse.query_tagging import get_query_tags, tag_queries
 from posthog.constants import AvailableFeature
 from posthog.direct_query_cancellation import build_direct_query_cancellation_token, request_direct_query_cancellation
-from posthog.errors import ExposedCHQueryError
+from posthog.errors import ExposedCHQueryError, clickhouse_error_type
 from posthog.exceptions import ClickHouseAtCapacity
 from posthog.exceptions_capture import capture_exception
 from posthog.renderers import SafeJSONRenderer
@@ -311,6 +311,11 @@ def execute_process_query(
                 codes = err.get_codes()
                 if isinstance(codes, str):
                     query_status.error_code = codes
+        if not query_status.error_code:
+            # The message text stays hidden when it's not user-safe, but the exception class is a
+            # stable, machine-readable cause (e.g. "CHQueryErrorMemoryLimitExceeded"). Carry it so
+            # callers can classify the failure instead of dead-ending on an opaque "Query failed".
+            query_status.error_code = clickhouse_error_type(err)
         logger.exception("Error processing query async", team_id=team_id, query_id=query_id, exc_info=True)
         if not is_user_safe_error:
             # User-safe errors (e.g. a malformed HogQL query) are already returned to the user as a 400,

posthog/clickhouse/client/test/test_execute_async.py

@@ -363,6 +363,23 @@ def test_async_query_user_safe_error_carries_error_code(self):
         assert result.error_message
         self.assertEqual(result.error_code, ClickHouseQueryMemoryLimitExceeded.default_code)
 
+    def test_async_query_non_user_safe_error_carries_error_code_without_message(self):
+        query = build_query("SELECT * FROM events")
+        query_id = uuid.uuid4().hex
+
+        with patch("posthog.api.services.query.process_query_dict", side_effect=Exception("sensitive detail")):
+            client.enqueue_process_query_task(
+                self.team, self.user.id, query, query_id=query_id, _test_only_bypass_celery=True
+            )
+
+        result = client.get_query_status(self.team.id, query_id)
+        self.assertTrue(result.error)
+        self.assertTrue(result.complete)
+        # The message stays hidden for a non-user-safe error, but the class name is carried as a
+        # machine-readable cause so callers can classify the failure.
+        self.assertIsNone(result.error_message)
+        self.assertEqual(result.error_code, "Exception")
+
     def test_async_query_server_errors(self):
         query = build_query("SELECT * FROM events")