fix: bound loader missing statement errors (#440)

## Summary
- Add `SQLStatementNotFoundError`, a `SQLFileNotFoundError` subclass for missing named SQL statements.
- Bound missing-statement messages to the requested name and loaded statement count instead of dumping available statement names.
- Update loader exception docs, changelog, and regression coverage for `get_sql()` and `get_query_text()`.

Fixes #437.

Author: cofin

docs/changelog.rst

@@ -15,6 +15,12 @@ v0.46.2 - Framework Filter ``orderBy`` Aliases (Unreleased)
 
 **Fixed:**
 
+* Missing named SQL statements now raise ``SQLStatementNotFoundError``, a
+  ``SQLFileNotFoundError`` subclass with structured lookup context and bounded
+  messages that report the loaded statement count instead of dumping available
+  statement names. (`#437
+  <https://github.com/litestar-org/sqlspec/issues/437>`_)
+
 * Litestar ``create_filter_dependencies()`` and FastAPI ``provide_filters()``
   now accept camel-case API-facing sort aliases for configured ``orderBy``
   fields by default. Endpoints can accept values such as

docs/reference/exceptions.rst

@@ -165,6 +165,10 @@ SQL Files
    :members:
    :show-inheritance:
 
+.. autoclass:: SQLStatementNotFoundError
+   :members:
+   :show-inheritance:
+
 .. autoclass:: SQLFileParseError
    :members:
    :show-inheritance:
@@ -241,6 +245,7 @@ Inheritance Tree
    |   +-- FileNotFoundInStorageError
    +-- StorageCapabilityError
    +-- SQLFileNotFoundError
+   |   +-- SQLStatementNotFoundError
    +-- SQLFileParseError
    +-- MigrationError
        +-- InvalidVersionFormatError

pyproject.toml

@@ -24,7 +24,7 @@ maintainers = [{ name = "Litestar Developers", email = "hello@litestar.dev" }]
 name = "sqlspec"
 readme = "README.md"
 requires-python = ">=3.10, <4.0"
-version = "0.46.2"
+version = "0.46.3"
 
 [project.urls]
 Discord = "https://discord.gg/litestar"
@@ -264,7 +264,7 @@ opt_level = "3"   # Maximum optimization (0-3)
 allow_dirty = true
 commit = false
 commit_args = "--no-verify"
-current_version = "0.46.2"
+current_version = "0.46.3"
 ignore_missing_files = false
 ignore_missing_version = false
 message = "chore(release): bump to v{new_version}"

sqlspec/exceptions.py

@@ -35,6 +35,7 @@
     "SQLFileParseError",
     "SQLParsingError",
     "SQLSpecError",
+    "SQLStatementNotFoundError",
     "SerializationConflictError",
     "SerializationError",
     "SquashValidationError",
@@ -323,6 +324,31 @@ def __init__(self, name: str, path: "str | None" = None) -> None:
         self.path = path
 
 
+class SQLStatementNotFoundError(SQLFileNotFoundError):
+    """Raised when a named SQL statement is not loaded."""
+
+    def __init__(self, name: str, normalized_name: str, query_count: int) -> None:
+        """Initialize the error.
+
+        Args:
+            name: Name requested by the caller.
+            normalized_name: Normalized statement name used for lookup.
+            query_count: Number of SQL statements loaded in the registry.
+        """
+        if query_count == 0:
+            message = f"SQL statement '{name}' not found. No SQL statements are loaded."
+        else:
+            message = (
+                f"SQL statement '{name}' not found. {query_count} SQL statements are loaded. "
+                "Use list_queries() to inspect available statement names."
+            )
+        SQLSpecError.__init__(self, message)
+        self.name = name
+        self.path = None
+        self.normalized_name = normalized_name
+        self.query_count = query_count
+
+
 class SQLFileParseError(SQLSpecError):
     """Raised when a SQL file cannot be parsed."""
 

sqlspec/loader.py

@@ -21,6 +21,7 @@
     FileNotFoundInStorageError,
     SQLFileNotFoundError,
     SQLFileParseError,
+    SQLStatementNotFoundError,
     StorageOperationFailedError,
 )
 from sqlspec.storage.registry import storage_registry as default_storage_registry
@@ -206,6 +207,18 @@ def _raise_file_not_found(self, path: str) -> None:
         """
         raise SQLFileNotFoundError(path)
 
+    def _raise_statement_not_found(self, name: str, normalized_name: str) -> None:
+        """Raise SQLStatementNotFoundError for nonexistent statements.
+
+        Args:
+            name: Name requested by the caller.
+            normalized_name: Normalized statement name used for lookup.
+
+        Raises:
+            SQLStatementNotFoundError: Always raised.
+        """
+        raise SQLStatementNotFoundError(name=name, normalized_name=normalized_name, query_count=len(self._queries))
+
     def _generate_file_cache_key(self, path: str | Path) -> str:
         """Generate cache key for a file path.
 
@@ -676,11 +689,11 @@ def get_query_text(self, name: str) -> str:
             Raw SQL text.
 
         Raises:
-            SQLFileNotFoundError: If query not found.
+            SQLStatementNotFoundError: If query not found.
         """
         safe_name = _normalize_query_name(name)
         if safe_name not in self._queries:
-            raise SQLFileNotFoundError(name)
+            self._raise_statement_not_found(name, safe_name)
         return self._queries[safe_name].sql
 
     def get_sql(self, name: str) -> "SQL":
@@ -694,13 +707,12 @@ def get_sql(self, name: str) -> "SQL":
             SQL object ready for execution.
 
         Raises:
-            SQLFileNotFoundError: If statement name not found.
+            SQLStatementNotFoundError: If statement name not found.
         """
         safe_name = _normalize_query_name(name)
 
         if safe_name not in self._queries:
-            available = ", ".join(sorted(self._queries.keys())) if self._queries else "none"
-            raise SQLFileNotFoundError(name, path=f"Statement '{name}' not found. Available statements: {available}")
+            self._raise_statement_not_found(name, safe_name)
 
         parsed_statement = self._queries[safe_name]
         sqlglot_dialect = None

tests/unit/exceptions/test_exceptions.py

@@ -7,7 +7,9 @@
     NotFoundError,
     NotNullViolationError,
     OperationalError,
+    SQLFileNotFoundError,
     SQLSpecError,
+    SQLStatementNotFoundError,
     StackExecutionError,
     TransactionError,
     UniqueViolationError,
@@ -25,6 +27,7 @@ def test_new_exception_hierarchy() -> None:
     assert issubclass(TransactionError, SQLSpecError)
     assert issubclass(DataError, SQLSpecError)
     assert issubclass(OperationalError, SQLSpecError)
+    assert issubclass(SQLStatementNotFoundError, SQLFileNotFoundError)
 
 
 def test_exception_instantiation() -> None:
@@ -149,6 +152,21 @@ def test_subclass_inherits_args_behavior() -> None:
     assert str(exc) == "item not found"
 
 
+def test_sql_statement_not_found_exposes_lookup_context() -> None:
+    """Test SQLStatementNotFoundError exposes bounded lookup context."""
+    exc = SQLStatementNotFoundError(name="missing-query", normalized_name="missing_query", query_count=12)
+
+    assert isinstance(exc, SQLFileNotFoundError)
+    assert exc.name == "missing-query"
+    assert exc.path is None
+    assert exc.normalized_name == "missing_query"
+    assert exc.query_count == 12
+    assert str(exc) == (
+        "SQL statement 'missing-query' not found. 12 SQL statements are loaded. "
+        "Use list_queries() to inspect available statement names."
+    )
+
+
 def test_stack_execution_error_preserves_args() -> None:
     """Test StackExecutionError correctly populates args."""
     original = ValueError("boom")

tests/unit/loader/test_sql_file_loader.py

@@ -10,13 +10,14 @@
 """
 
 import time
+from collections.abc import Callable
 from pathlib import Path
 from typing import Any
 
 import pytest
 
 from sqlspec.core import SQL
-from sqlspec.exceptions import SQLFileNotFoundError, SQLFileParseError
+from sqlspec.exceptions import SQLFileNotFoundError, SQLFileParseError, SQLStatementNotFoundError
 from sqlspec.loader import (
     NamedStatement,
     SQLFile,
@@ -510,6 +511,44 @@ def test_get_query_text_not_found() -> None:
         loader.get_query_text("nonexistent")
 
 
+@pytest.mark.parametrize("accessor", [SQLFileLoader.get_sql, SQLFileLoader.get_query_text])
+def test_missing_statement_empty_loader_message(accessor: Callable[[SQLFileLoader, str], object]) -> None:
+    """Missing statements in an empty loader should return a bounded message."""
+    loader = SQLFileLoader()
+
+    with pytest.raises(SQLStatementNotFoundError) as exc_info:
+        accessor(loader, "missing-secret")
+
+    exc = exc_info.value
+    assert str(exc) == "SQL statement 'missing-secret' not found. No SQL statements are loaded."
+    assert exc.name == "missing-secret"
+    assert exc.normalized_name == "missing_secret"
+    assert exc.query_count == 0
+
+
+@pytest.mark.parametrize("accessor", [SQLFileLoader.get_sql, SQLFileLoader.get_query_text])
+def test_missing_statement_loaded_registry_message_does_not_leak_names(
+    accessor: Callable[[SQLFileLoader, str], object],
+) -> None:
+    """Missing statements should not dump the loaded statement registry."""
+    loader = SQLFileLoader()
+    loaded_query_names = [f"tenant_{index}_private_query" for index in range(20)]
+    for query_name in loaded_query_names:
+        loader.add_named_sql(query_name, "SELECT 1")
+
+    with pytest.raises(SQLStatementNotFoundError) as exc_info:
+        accessor(loader, "missing-secret")
+
+    message = str(exc_info.value)
+    assert message == (
+        "SQL statement 'missing-secret' not found. 20 SQL statements are loaded. "
+        "Use list_queries() to inspect available statement names."
+    )
+    assert "Available statements" not in message
+    for query_name in loaded_query_names:
+        assert query_name not in message
+
+
 def test_clear_cache() -> None:
     """Test clearing loader cache."""
     loader = SQLFileLoader()
@@ -582,7 +621,7 @@ def test_get_sql_not_found() -> None:
     with pytest.raises(SQLFileNotFoundError) as exc_info:
         loader.get_sql("nonexistent")
 
-    assert "Statement 'nonexistent' not found" in str(exc_info.value)
+    assert "SQL statement 'nonexistent' not found" in str(exc_info.value)
 
 
 def test_get_sql_name_normalization() -> None: