Classify ToolCallErrors as client/server and catch COMPILED timeouts (#608)

## Why

dbt-mcp errors currently have no classification for whether they
represent client-side (bad input) or server-side failures. Downstream
consumers like ACA need this distinction to return correct HTTP status
codes and log at appropriate levels.

Additionally, semantic layer queries that timeout after reaching
COMPILED status indicate the query is too complex for an agent context,
but this wasn't surfaced as a distinct error.

## What

- Added typed union aliases `ClientToolCallError` and
`ServerToolCallError` in `errors/__init__.py` — `isinstance()` works at
runtime
- Added `SemanticLayerQueryTimeoutError` for queries that timeout with
COMPILED status, indicating the query compiled successfully but is too
complex to execute in an agent context
- Catch `RetryTimeoutError` with COMPILED status in
`SemanticLayerFetcher.query_metrics` and raise
`SemanticLayerQueryTimeoutError` (other timeout statuses fall through to
the existing error handling)
- Bumped `dbt-sl-sdk` from `==0.13.1` to `>=0.13.2` (needed for
`RetryTimeoutError.status`)
- Added missing `NotFoundError` and `SemanticLayerQueryTimeoutError`
exports
- Added exhaustiveness tests ensuring every `ToolCallError` subclass is
classified in exactly one union
- Added unit tests for COMPILED timeout behavior

Drafted by Claude Opus 4.6 under the direction of @DevonFulcher

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: DevonFulcher

.changes/unreleased/Under the Hood-20260223-131753.yaml

@@ -0,0 +1,3 @@
+kind: Under the Hood
+body: Classify ToolCallErrors as client/server via TypeAlias unions and catch COMPILED timeouts as SemanticLayerQueryTimeoutError
+time: 2026-02-23T13:17:53.310801-06:00

pyproject.toml

@@ -30,7 +30,7 @@ classifiers = [
 dependencies = [
   "authlib==1.6.6",
   "dbt-protos==1.0.382",
-  "dbt-sl-sdk[sync]==0.13.1",
+  "dbt-sl-sdk[sync]>=0.13.2",
   "dbtlabs-vortex==0.2.0",
   "fastapi>=0.116.1",
   "uvicorn>=0.31.1",

src/dbt_mcp/errors/__init__.py

@@ -5,22 +5,48 @@
 )
 from dbt_mcp.errors.base import ToolCallError
 from dbt_mcp.errors.cli import BinaryExecutionError, CLIToolCallError
-from dbt_mcp.errors.common import InvalidParameterError
+from dbt_mcp.errors.common import InvalidParameterError, NotFoundError
 from dbt_mcp.errors.discovery import DiscoveryToolCallError, GraphQLError
-from dbt_mcp.errors.semantic_layer import SemanticLayerToolCallError
+from dbt_mcp.errors.semantic_layer import (
+    SemanticLayerQueryTimeoutError,
+    SemanticLayerToolCallError,
+)
 from dbt_mcp.errors.sql import RemoteToolError, SQLToolCallError
 
+ClientToolCallError = (
+    InvalidParameterError
+    | NotFoundError
+    | SemanticLayerQueryTimeoutError
+    | GraphQLError
+)
+
+ServerToolCallError = (
+    SemanticLayerToolCallError
+    | CLIToolCallError
+    | BinaryExecutionError
+    | SQLToolCallError
+    | RemoteToolError
+    | DiscoveryToolCallError
+    | AdminAPIToolCallError
+    | AdminAPIError
+    | ArtifactRetrievalError
+)
+
 __all__ = [
     "AdminAPIError",
     "AdminAPIToolCallError",
     "ArtifactRetrievalError",
     "BinaryExecutionError",
     "CLIToolCallError",
+    "ClientToolCallError",
     "DiscoveryToolCallError",
     "GraphQLError",
     "InvalidParameterError",
+    "NotFoundError",
     "RemoteToolError",
     "SQLToolCallError",
+    "SemanticLayerQueryTimeoutError",
     "SemanticLayerToolCallError",
+    "ServerToolCallError",
     "ToolCallError",
 ]

src/dbt_mcp/errors/semantic_layer.py

@@ -7,3 +7,14 @@ class SemanticLayerToolCallError(ToolCallError):
     """Base exception for Semantic Layer tool errors."""
 
     pass
+
+
+class SemanticLayerQueryTimeoutError(SemanticLayerToolCallError):
+    """Exception raised when a semantic layer query times out with COMPILED status.
+
+    A COMPILED timeout means the query finished SQL compilation and is executing
+    against the data platform. In agent contexts this indicates the query is too
+    complex or returns too much data, and the client should simplify the request.
+    """
+
+    pass

src/dbt_mcp/semantic_layer/client.py

@@ -15,10 +15,12 @@
     OrderBySpec,
 )
 from dbtsl.client.sync import SyncSemanticLayerClient
-from dbtsl.error import QueryFailedError
+from dbtsl.error import QueryFailedError, RetryTimeoutError
+from dbtsl.models.query import QueryStatus
 
 from dbt_mcp.config.config_providers import ConfigProvider, SemanticLayerConfig
 from dbt_mcp.errors import InvalidParameterError
+from dbt_mcp.errors.semantic_layer import SemanticLayerQueryTimeoutError
 from dbt_mcp.semantic_layer.gql.gql import GRAPHQL_QUERIES
 from dbt_mcp.semantic_layer.gql.gql_request import submit_request
 from dbt_mcp.semantic_layer.types import (
@@ -341,7 +343,7 @@ async def query_metrics(
         result_formatter: Callable[[pa.Table], str] | None = None,
     ) -> QueryMetricsResult:
         try:
-            query_error = None
+            query_error: Exception | None = None
             sl_client = await self.client_provider.get_client()
             with sl_client.session():
                 # Catching any exception within the session
@@ -358,12 +360,28 @@ async def query_metrics(
                         where=[where] if where else None,
                         limit=limit,
                     )
+                except RetryTimeoutError as e:
+                    # Queries that timeout with COMPILED status have finished SQL
+                    # compilation and are executing against the data platform. In
+                    # agent contexts, this indicates the query is too complex and
+                    # the client should request a simpler query.
+                    if e.status == QueryStatus.COMPILED.value:
+                        raise SemanticLayerQueryTimeoutError(
+                            f"The semantic layer query timed out after {e.timeout_s}s while "
+                            f"executing against the data platform (status: COMPILED). This "
+                            f"indicates the query is too complex or returns too much data "
+                            f"for an agent context. Please simplify the query by adding "
+                            f"filters, reducing dimensions, or limiting results."
+                        ) from e
+                    query_error = e
                 except Exception as e:
                     query_error = e
             if query_error:
                 return self._format_query_failed_error(query_error)
             formatter = result_formatter or DEFAULT_RESULT_FORMATTER
             json_result = formatter(query_result)
             return QueryMetricsSuccess(result=json_result or "")
+        except SemanticLayerQueryTimeoutError:
+            raise
         except Exception as e:
             return self._format_query_failed_error(e)

tests/unit/errors/__init__.py

@@ -0,0 +1,68 @@
+"""Tests for typed union exhaustiveness of ToolCallError classification."""
+
+from typing import get_args
+
+from dbt_mcp.errors import (
+    ClientToolCallError,
+    ServerToolCallError,
+)
+from dbt_mcp.errors.base import ToolCallError as BaseToolCallError
+
+
+def _get_all_subclasses(cls: type) -> set[type]:
+    """Recursively collect all subclasses of a class."""
+    result = set()
+    for subclass in cls.__subclasses__():
+        result.add(subclass)
+        result.update(_get_all_subclasses(subclass))
+    return result
+
+
+class TestUnionExhaustiveness:
+    """Ensure every ToolCallError subclass is classified in exactly one union."""
+
+    def test_all_subclasses_are_classified(self) -> None:
+        client_types = set(get_args(ClientToolCallError))
+        server_types = set(get_args(ServerToolCallError))
+        all_classified = client_types | server_types
+
+        all_subclasses = _get_all_subclasses(BaseToolCallError)
+
+        unclassified = set()
+        for subclass in all_subclasses:
+            # A subclass is classified if it is in a union OR if any of its
+            # parent classes (other than ToolCallError) is in a union.
+            classified = False
+            for cls in subclass.__mro__:
+                if cls in all_classified:
+                    classified = True
+                    break
+            if not classified:
+                unclassified.add(subclass)
+
+        assert unclassified == set(), (
+            f"Unclassified ToolCallError subclasses: {unclassified}. "
+            "Add them to ClientToolCallError or ServerToolCallError in errors/__init__.py."
+        )
+
+    def test_no_overlap_between_client_and_server(self) -> None:
+        client_types = set(get_args(ClientToolCallError))
+        server_types = set(get_args(ServerToolCallError))
+        overlap = client_types & server_types
+        assert overlap == set(), (
+            f"Types appear in both ClientToolCallError and ServerToolCallError: {overlap}"
+        )
+
+
+class TestIsInstanceWorks:
+    """Verify isinstance checks work with the typed unions at runtime."""
+
+    def test_isinstance_client_error(self) -> None:
+        for error_type in get_args(ClientToolCallError):
+            instance = error_type("test")
+            assert isinstance(instance, ClientToolCallError)
+
+    def test_isinstance_server_error(self) -> None:
+        for error_type in get_args(ServerToolCallError):
+            instance = error_type("test")
+            assert isinstance(instance, ServerToolCallError)

tests/unit/errors/test_error_classification.py

@@ -6,8 +6,11 @@
 
 import pyarrow as pa
 import pytest
+from dbtsl.error import RetryTimeoutError
 
+from dbt_mcp.errors.semantic_layer import SemanticLayerQueryTimeoutError
 from dbt_mcp.semantic_layer.client import DEFAULT_RESULT_FORMATTER, SemanticLayerFetcher
+from dbt_mcp.semantic_layer.types import QueryMetricsError
 
 
 def test_default_result_formatter_outputs_iso_dates() -> None:
@@ -376,3 +379,62 @@ async def test_get_dimensions_includes_metadata(
     assert result[0].metadata == {"display_name": "Order Date"}
     assert result[1].metadata is None
     assert result[2].metadata is None
+
+
+class TestQueryMetricsCompiledTimeout:
+    """Tests for COMPILED timeout handling in query_metrics."""
+
+    @pytest.fixture
+    def mock_sl_client(self):
+        client = MagicMock()
+        session_ctx = MagicMock()
+        client.session.return_value = session_ctx
+        session_ctx.__enter__ = MagicMock(return_value=client)
+        session_ctx.__exit__ = MagicMock(return_value=False)
+        return client
+
+    @pytest.fixture
+    def compiled_fetcher(self, mock_config_provider, mock_sl_client):
+        client_provider = AsyncMock()
+        client_provider.get_client.return_value = mock_sl_client
+        return SemanticLayerFetcher(
+            config_provider=mock_config_provider,
+            client_provider=client_provider,
+        )
+
+    async def test_compiled_timeout_raises_client_error(
+        self, compiled_fetcher, mock_sl_client
+    ):
+        """COMPILED status timeout should raise SemanticLayerQueryTimeoutError."""
+        mock_sl_client.query.side_effect = RetryTimeoutError(
+            timeout_s=60, status="COMPILED"
+        )
+
+        with pytest.raises(SemanticLayerQueryTimeoutError) as exc_info:
+            await compiled_fetcher.query_metrics(metrics=["revenue"])
+
+        assert "COMPILED" in str(exc_info.value)
+
+    async def test_running_timeout_returns_error_result(
+        self, compiled_fetcher, mock_sl_client
+    ):
+        """RUNNING status timeout should return QueryMetricsError, not raise."""
+        mock_sl_client.query.side_effect = RetryTimeoutError(
+            timeout_s=60, status="RUNNING"
+        )
+
+        result = await compiled_fetcher.query_metrics(metrics=["revenue"])
+
+        assert isinstance(result, QueryMetricsError)
+        assert result.error is not None
+
+    async def test_none_status_timeout_returns_error_result(
+        self, compiled_fetcher, mock_sl_client
+    ):
+        """None status timeout should return QueryMetricsError, not raise."""
+        mock_sl_client.query.side_effect = RetryTimeoutError(timeout_s=60)
+
+        result = await compiled_fetcher.query_metrics(metrics=["revenue"])
+
+        assert isinstance(result, QueryMetricsError)
+        assert result.error is not None