Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

feat(query): return a fixable error for unreadable result columns (#120081)

Vasco de Krijger403a6b0ed0ff
diff --git a/ee/hogai/tools/execute_sql/test/test_mcp_tool.py b/ee/hogai/tools/execute_sql/test/test_mcp_tool.py
index be101332bc3b..405cf17f7ad4 100644
--- a/ee/hogai/tools/execute_sql/test/test_mcp_tool.py
+++ b/ee/hogai/tools/execute_sql/test/test_mcp_tool.py
@@ -124,8 +124,14 @@ class TestExecuteSQLMCPTool(ClickhouseTestMixin, NonAtomicBaseTest):
with self.assertRaises(MaxToolRetryableError) as ctx:
await self.tool.execute(ExecuteSQLMCPToolArgs(query="SELECT argMinState(event, timestamp) FROM events"))
- self.assertEqual(ctx.exception.error_type, "internal")
- self.assertEqual(ctx.exception.error_code, "unhandled_unknown_type_error")
+ self.assertEqual(ctx.exception.error_type, "validation")
+ self.assertEqual(ctx.exception.error_code, "unknown_type")
+ self.assertEqual(
+ str(ctx.exception),
+ "This query returns a column of type `AggregateFunction(argMin, String, DateTime64(6, 'UTC'))`, which "
+ "PostHog can't send back in results. The column holds a stored aggregate state. Wrap it in the matching "
+ "-Merge function, for example `argMinMerge(column)`, to get the final value.",
+ )
@parameterized.expand(
[
diff --git a/posthog/errors.py b/posthog/errors.py
index 10a86bd72283..556d91a4a970 100644
--- a/posthog/errors.py
+++ b/posthog/errors.py
@@ -3,7 +3,7 @@ from dataclasses import dataclass
from enum import StrEnum
from typing import Optional
-from clickhouse_driver.errors import NetworkError, ServerException, SocketTimeoutError
+from clickhouse_driver.errors import NetworkError, ServerException, SocketTimeoutError, UnknownTypeError
from posthog.hogql.errors import ExposedHogQLError
@@ -125,8 +125,35 @@ def _wrap_bad_get_error(err: ServerException) -> "CHQueryErrorBadGet":
return CHQueryErrorBadGet(message, code=err.code, code_name="bad_get")
+def _unreadable_type_advice(unreadable_type: str) -> str:
+ if unreadable_type.startswith("AggregateFunction("):
+ return (
+ "The column holds a stored aggregate state. "
+ "Wrap it in the matching -Merge function, for example `argMinMerge(column)`, to get the final value."
+ )
+ if unreadable_type.startswith("Variant("):
+ return (
+ "The column mixes value types. This usually comes from `UNION ALL` branches, `coalesce()` or "
+ "`ifNull()` arguments, or `if()` branches that return different types. "
+ "Make them return one type, for example with `toString()` or `toFloat()`."
+ )
+ return "Convert the column to a basic type such as a string, number, or date, or leave it out of the results."
+
+
+def _wrap_unknown_type_error(err: UnknownTypeError) -> "CHQueryErrorUnknownType":
+ unreadable_type = err.message.removeprefix("Unknown type ")
+ advice = _unreadable_type_advice(unreadable_type)
+ return CHQueryErrorUnknownType(
+ f"This query returns a column of type `{unreadable_type}`, which PostHog can't send back in results. {advice}",
+ code=err.code,
+ code_name="unknown_type",
+ )
+
+
def wrap_clickhouse_query_error(err: Exception) -> Exception:
"Beautifies clickhouse client errors, using custom error classes for every code"
+ if isinstance(err, UnknownTypeError):
+ return _wrap_unknown_type_error(err)
if not isinstance(err, ServerException):
return err
@@ -299,6 +326,10 @@ class CHQueryErrorBadGet(ExposedCHQueryError):
pass
+class CHQueryErrorUnknownType(ExposedCHQueryError):
+ pass
+
+
class CHQueryErrorNoCommonType(ExposedCHQueryError):
pass
diff --git a/posthog/hogql_queries/test/test_query_failure_handling.py b/posthog/hogql_queries/test/test_query_failure_handling.py
index d93f41cc2292..f8a44e79297e 100644
--- a/posthog/hogql_queries/test/test_query_failure_handling.py
+++ b/posthog/hogql_queries/test/test_query_failure_handling.py
@@ -6,7 +6,7 @@ from unittest.mock import patch
from django.test import SimpleTestCase
-from clickhouse_driver.errors import ServerException
+from clickhouse_driver.errors import ServerException, UnknownTypeError
from parameterized import parameterized
from rest_framework.exceptions import ValidationError
@@ -62,6 +62,13 @@ def _clickhouse_error(message: str, code: int) -> Exception:
return error
+def _unreadable_result_type_error() -> Exception:
+ driver_error = UnknownTypeError("Unknown type AggregateFunction(argMin, String, UInt8)")
+ error = wrap_clickhouse_query_error(driver_error)
+ error.__cause__ = driver_error
+ return error
+
+
def _wrapped_by_the_app() -> Exception:
error = DatabaseSchemaUnavailable()
error.__cause__ = ServerException("Cannot compare", code=386)
@@ -79,6 +86,7 @@ class TestSharedFailures(SimpleTestCase):
"per_query_memory_limit",
lambda: _clickhouse_error("Memory limit (for query) exceeded: would use 30.1 GiB", 241),
),
+ ("unreadable_result_type", _unreadable_result_type_error),
("hogql_query_error", lambda: QueryError("Unknown field: nope", start=7, end=11)),
("hogql_syntax_error", lambda: HogQLSyntaxError("Unexpected token", start=0, end=3, fix="select")),
]
diff --git a/posthog/test/test_errors.py b/posthog/test/test_errors.py
index 3d5481134ccc..e1e6be2baeb6 100644
--- a/posthog/test/test_errors.py
+++ b/posthog/test/test_errors.py
@@ -1,4 +1,4 @@
-from clickhouse_driver.errors import ServerException
+from clickhouse_driver.errors import ServerException, UnknownTypeError
from parameterized import parameterized
from posthog.errors import (
@@ -7,6 +7,7 @@ from posthog.errors import (
CHQueryErrorCannotParseBool,
CHQueryErrorCannotParseUuid,
CHQueryErrorInvalidJoinOnExpression,
+ CHQueryErrorUnknownType,
ExposedCHQueryError,
InternalCHQueryError,
QueryErrorCategory,
@@ -179,6 +180,40 @@ class TestWrapClickhouseQueryError:
assert wrapped.nested is None
assert look_up_clickhouse_error_code_meta(err).get_category() == QueryErrorCategory.USER_ERROR
+ @parameterized.expand(
+ [
+ (
+ "aggregate_state",
+ "AggregateFunction(argMin, Nullable(String), DateTime64(6, 'UTC'))",
+ "This query returns a column of type `AggregateFunction(argMin, Nullable(String), DateTime64(6, 'UTC'))`, "
+ "which PostHog can't send back in results. The column holds a stored aggregate state. Wrap it in the "
+ "matching -Merge function, for example `argMinMerge(column)`, to get the final value.",
+ ),
+ (
+ "mixed_value_types",
+ "Variant(Int64, UInt64)",
+ "This query returns a column of type `Variant(Int64, UInt64)`, which PostHog can't send back in "
+ "results. The column mixes value types. This usually comes from `UNION ALL` branches, `coalesce()` "
+ "or `ifNull()` arguments, or `if()` branches that return different types. Make them return one "
+ "type, for example with `toString()` or `toFloat()`.",
+ ),
+ (
+ "other_type",
+ "JSON",
+ "This query returns a column of type `JSON`, which PostHog can't send back in results. Convert the "
+ "column to a basic type such as a string, number, or date, or leave it out of the results.",
+ ),
+ ]
+ )
+ def test_unreadable_result_type_names_the_fix_for_its_type(
+ self, _name: str, column_type: str, expected_message: str
+ ) -> None:
+ wrapped = wrap_clickhouse_query_error(UnknownTypeError(f"Unknown type {column_type}"))
+
+ assert isinstance(wrapped, CHQueryErrorUnknownType)
+ assert wrapped.code_name == "unknown_type"
+ assert str(wrapped) == expected_message
+
def test_bad_get_hides_unrecognized_raw_message(self) -> None:
err = ServerException(
"DB::Exception: Bad get: has private-row-value, requested UInt64. While processing private-query-context.",