fix(volume): preserve local validation errors and document release gate

Signed-off-by: Aakash Saravanan <aakash.saravanan@databricks.com>

Author: aakash-saravanan-db

KERNEL_REV

@@ -1 +1 @@
-ebb8204b36951b751dd837b2c41ced8c821b2d94
+02283500d50e1bcd61007e0cf04a7e1e3d16ea86

pyproject.toml

@@ -70,6 +70,7 @@ requests-kerberos = {version = "^0.15.0", optional = true}
 # Floor is 1.4.0 (``^1.4.0`` == ``>=1.4.0,<2.0.0``), allowing compatible
 # 1.x releases while keeping the next major upgrade deliberate. The kernel's
 # pyarrow constraint remains >=23.0.1,<24.
+# TODO: raise the release floor after databricks/databricks-sql-kernel#439 is published.
 databricks-sql-kernel = {version = "^1.4.0", optional = true, python = ">=3.10"}
 
 

src/databricks/sql/backend/kernel/_errors.py

@@ -17,6 +17,9 @@
   "only PEP 249 exception types cross the boundary". Wrapped in
   ``OperationalError`` here.
 
+Local missing transfer files deliberately retain the built-in
+``FileNotFoundError`` contract.
+
 These primitives live in their own module so both ``client.py``
 (which orchestrates PyO3 calls) and ``result_set.py`` (which calls
 ``fetch_next_batch`` on the same kernel handles) can share them
@@ -133,7 +136,8 @@ def reraise_kernel_error(
     if file_transfer:
         cls = (
             ProgrammingError
-            if code == "PermissionDenied" and getattr(exc, "http_status", None) is None
+            if code in ("PermissionDenied", "InvalidArgument")
+            and getattr(exc, "http_status", None) is None
             else OperationalError
         )
 
@@ -185,9 +189,10 @@ def reraise_kernel_error(
 def wrap_kernel_exception(
     what: str, exc: BaseException
 ) -> "Union[Error, FileNotFoundError]":
-    """Map any exception from a PyO3 call site to a PEP 249 exception.
+    """Map a PyO3 exception to the connector's public error contract.
 
     - ``KernelError`` → mapped class with structured attrs forwarded.
+      A local missing transfer file maps to ``FileNotFoundError``.
     - Already-PEP-249 ``Error`` (e.g. raised by an inner caller that
       already mapped) → passed through unchanged.
     - Anything else (``TypeError`` / ``ValueError`` / etc. from PyO3

src/databricks/sql/client.py

@@ -1394,7 +1394,7 @@ def _handle_staging_put(
                 session_id_hex=self.connection.get_session_id_hex(),
             )
 
-        # Kernel backends reject staging operations before reaching these handlers.
+        # The kernel completes configured transfers before reaching these handlers.
         assert self.connection.http_client is not None
         with open(local_file, "rb") as fh:
             r = self.connection.http_client.request(

tests/e2e/test_kernel_backend.py

@@ -367,7 +367,9 @@ def test_schemas_with_empty_string_filter_matches_nothing(conn):
         assert cur.fetchall() == []
 
 
-@pytest.mark.parametrize("empty_filter", ["schema_name", "table_name", "column_name"])
+@pytest.mark.parametrize(
+    "empty_filter", ["schema_name", "table_name", "column_name"]
+)
 def test_columns_with_empty_string_filter_matches_nothing(conn, empty_filter):
     filters = {
         "catalog_name": "system",
@@ -798,6 +800,13 @@ def test_volume_file_lifecycle(kernel_conn_params, tmp_path, catalog, async_op):
             try:
                 cur.execute(f"CREATE VOLUME {qualified}.files")
 
+                with sql.connect(**kernel_conn_params) as no_paths:
+                    with no_paths.cursor() as denied_cursor:
+                        with pytest.raises(ProgrammingError):
+                            denied_cursor.execute(
+                                f"PUT '{source}' INTO '{remote}' OVERWRITE"
+                            )
+
                 def execute(query):
                     if async_op:
                         cur.execute_async(query)

tests/unit/test_kernel_client.py

@@ -2621,6 +2621,7 @@ def test_only_reserved_headers_omits_kwarg(self, monkeypatch):
     "code, http_status, expected",
     [
         ("PermissionDenied", None, ProgrammingError),
+        ("InvalidArgument", None, ProgrammingError),
         ("PermissionDenied", 403, OperationalError),
         ("NotFound", None, FileNotFoundError),
         ("NotFound", 404, OperationalError),