This is an automated email from the ASF dual-hosted git repository.

HyukjinKwon pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/spark-connect-rust.git


The following commit(s) were added to refs/heads/master by this push:
     new a9cf050  [SPARK-60911][CONNECT] Raise server errors with the exception 
class and details PySpark gives
a9cf050 is described below

commit a9cf050ec1acd648e6466a82d1b4f832994ed209
Author: Hyukjin Kwon <[email protected]>
AuthorDate: Thu Nov 5 18:51:49 2026 +0900

    [SPARK-60911][CONNECT] Raise server errors with the exception class and 
details PySpark gives
    
    ### What changes were proposed in this pull request?
    
    [SPARK-60911](https://issues.apache.org/jira/browse/SPARK-60911): an error 
that the server raises now becomes, in the Python client, the exception that 
PySpark Connect 4.3.0 raises, with the same details. The Rust API gets the same 
details.
    
    - The core reads a server error's `ErrorInfo` as PySpark's 
`convert_exception` does: the exception classes, condition, message parameters 
in the server's order, SQL state and stack trace. When the server keeps the 
error (`errorId`), the client fetches it with `FetchErrorDetails`, for the full 
message, the stack trace with its causes, the message parameters, query 
contexts and breaking-change info. As in PySpark's `_handle_rpc_error`, it 
reads `spark.sql.connect.serverStacktrace.enable [...]
    - The kind of a server error comes from the first of its classes, from the 
most specific one, that PySpark's `EXCEPTION_CLASS_MAPPING` maps. Before, a 
fixed list of names was checked in turn, so a `ParseException`, which is also 
an `AnalysisException`, was taken for the latter.
    - The message of a server error is the server's, which names the condition 
once. Before, the condition was prepended to it again.
    - `pyspark.errors.exceptions.connect` now has the classes of PySpark 4.3.0, 
which subclass `SparkConnectGrpcException` and the base classes, instead of 
aliases of the base classes. The Rust transport passes what it read to 
`_convert_server_error`, which picks and builds the exception as the rest of 
PySpark's `_convert_exception` does. `grpc` stays optional: without it, 
`StatusCode` is an enum with the members of `grpc.StatusCode`.
    - `SparkError` gets `server`, a boxed `ServerErrorInfo` with the classes, 
reason, error id, parameter order, whether to show the stack trace, and the 
breaking change, and `SparkErrorKind::Spark` is new. `spark_connect` now 
re-exports `SparkErrorKind`, `ServerErrorInfo`, `BreakingChangeInfo`, 
`QueryContext` and `QueryContextType`.
    
    ### Why are the changes needed?
    
    Server errors lost what PySpark gives:
    
    - `spark.sql("SELEC 1")` raised `AnalysisException` rather than 
`ParseException`.
    - `getCondition()`, `getMessageParameters()` and `getSqlState()` returned 
`None`, there was no `getStackTrace()`, and `getQueryContext()` was empty.
    - `str(e)` repeated the condition, as in `[TABLE_OR_VIEW_NOT_FOUND] 
[TABLE_OR_VIEW_NOT_FOUND] The table or view ...`, and showed no stack trace, 
and `getMessage()` started with `[None]`.
    - `except SparkConnectGrpcException` caught every PySpark error, while 
catching `pyspark.errors.exceptions.connect.SparkException`, as `ml/util.py` 
does, caught none.
    
    ### Does this PR introduce _any_ user-facing change?
    
    Yes, server errors now match PySpark Connect 4.3.0: their classes, 
`getCondition()`, `getMessageParameters()`, `getSqlState()`, `getStackTrace()`, 
`getQueryContext()` with SQL query contexts, `getBreakingChangeInfo()`, 
`getGrpcStatusCode()`, and `str(e)`, which shows the server's stack trace when 
`spark.sql.connect.serverStacktrace.enabled` is true, its default. Errors that 
do not come from the server, such as a failed connection, are unchanged.
    
    The query contexts of DataFrame API calls need the client to send their 
call sites, which it does not yet: 
[SPARK-60915](https://issues.apache.org/jira/browse/SPARK-60915).
    
    ### How was this patch tested?
    
    - Against a local Spark 4.3.0 server, probes of a syntax error, a missing 
table, a missing column, an invalid `SET` and a division by zero give the same 
output as official PySpark 4.3.0 for the class and its superclasses, the 
condition, SQL state, message parameters, message, stack trace and SQL query 
contexts. What still differs is the DataFrame query context of the missing 
column (SPARK-60915) and, for the syntax error, the stack trace of failing at 
the action rather than at `sql()` [...]
    - New offline tests over the mock server, which can now fail with a server 
error and answers `FetchErrorDetails` and `Config`, check an error with 
details, one without them under each stack trace setting, and the exception 
that each kind of server error raises. They also pass with official PySpark 
4.3.0 over the same mock.
    - New unit tests check reading the `ErrorInfo`, the parameter order, the 
class mapping, completing an error with its details, and the stack trace with 
its causes.
    - New e2e tests, in Rust and Python, check a syntax error, a missing table 
and a division by zero. The Python one also passes with official PySpark 4.3.0.
    - The official `test_connect_error.py` and `test_parity_errors.py` through 
our transport (13 and 7 passed, and the one test that the manifest skips).
    - The core crate's tests (103 passed), the lib tests and every integration 
test, e2e included, against the local server (629 passed), the build of all 
tests with `wasm-udf`, the offline Python suites (432 passed, 8 live cases 
skipped), and the live drop-in and Arrow suites (22 passed) and live cases (9 
passed). Clippy reports no diagnostics in the changed lines.
    
    ### Was this patch authored or co-authored using generative AI tooling?
    
    Generated-by: Claude Opus 5.5
    
    This pull request and its description were written by Isaac.
    
    Closes #153 from HyukjinKwon/SPARK-60911-server-errors.
    
    Authored-by: Hyukjin Kwon <[email protected]>
    Signed-off-by: Hyukjin Kwon <[email protected]>
---
 Cargo.lock                                        |   1 +
 crates/pyspark-rs/src/errors.rs                   |  88 ++-
 crates/spark-connect-core/Cargo.toml              |   1 +
 crates/spark-connect-core/src/client.rs           | 156 +++--
 crates/spark-connect-core/src/error.rs            | 801 +++++++++++++++++-----
 crates/spark-connect/src/catalog.rs               |   8 +-
 crates/spark-connect/src/lib.rs                   |   5 +-
 crates/spark-connect/src/streaming.rs             |  10 +-
 crates/spark-connect/tests/e2e_session_catalog.rs |  39 ++
 python/pyspark/errors/exceptions/__init__.py      |   9 +-
 python/pyspark/errors/exceptions/connect.py       | 506 ++++++++++++--
 python/tests/_mock_connect_server.py              |  53 ++
 python/tests/test_dropin_e2e.py                   |  34 +
 python/tests/test_dropin_offline.py               | 221 +++++-
 14 files changed, 1627 insertions(+), 305 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index cd25ca0..3b65c41 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -86,6 +86,7 @@ dependencies = [
  "prost",
  "prost-types",
  "regex",
+ "serde",
  "serde_json",
  "sha2",
  "tempfile",
diff --git a/crates/pyspark-rs/src/errors.rs b/crates/pyspark-rs/src/errors.rs
index ea079cf..1da4078 100644
--- a/crates/pyspark-rs/src/errors.rs
+++ b/crates/pyspark-rs/src/errors.rs
@@ -2,7 +2,8 @@
 
 use pyo3::exceptions;
 use pyo3::prelude::*;
-use spark_connect_core::error::{SparkError, SparkErrorKind};
+use pyo3::types::{PyDict, PyList};
+use spark_connect_core::error::{ServerErrorInfo, SparkError, SparkErrorKind};
 
 /// Maps a SparkErrorKind to the corresponding pyspark.errors exception class 
name.
 /// Returns a string that can be used to retrieve the class from the 
pyspark.errors module.
@@ -44,13 +45,87 @@ fn kind_to_pyspark_class_name(kind: SparkErrorKind) -> 
&'static str {
         SparkErrorKind::PickleException => "PickleException",
 
         // Connect-specific exceptions: these don't exist in the vendored 
pyspark.errors,
-        // so we fall back to PySparkRuntimeError
+        // so we fall back to PySparkRuntimeError. An error that the server 
raised is built by
+        // `server_error_to_py` instead.
         SparkErrorKind::Connect => "PySparkRuntimeError",
         SparkErrorKind::ConnectGrpc => "PySparkRuntimeError",
         SparkErrorKind::InvalidPlanInput => "PySparkRuntimeError",
+        SparkErrorKind::Spark => "PySparkRuntimeError",
     }
 }
 
+/// The exception for an error that the server raised, as the reference client 
raises it:
+/// `pyspark.errors.exceptions.connect._convert_server_error` picks and builds 
it, as the
+/// reference client's `_convert_exception` does, from what the transport read 
of the error's
+/// `ErrorInfo` and `FetchErrorDetails`.
+fn server_error_to_py<'py>(
+    py: Python<'py>,
+    err: &SparkError,
+    server: &ServerErrorInfo,
+) -> PyResult<Bound<'py, PyAny>> {
+    let contexts = PyList::empty(py);
+    for context in &err.contexts {
+        let fields = PyDict::new(py);
+        fields.set_item("context_type", context.context_type.to_string())?;
+        fields.set_item("object_type", &context.object_type)?;
+        fields.set_item("object_name", &context.object_name)?;
+        fields.set_item("start_index", context.start_index)?;
+        fields.set_item("stop_index", context.stop_index)?;
+        fields.set_item("fragment", &context.fragment)?;
+        fields.set_item("call_site", &context.call_site)?;
+        fields.set_item("summary", &context.summary)?;
+        contexts.append(fields)?;
+    }
+    let breaking_change = match &server.breaking_change {
+        Some(change) => {
+            let info = PyDict::new(py);
+            info.set_item("migration_message", &change.migration_message)?;
+            info.set_item("needs_audit", change.needs_audit)?;
+            if let Some((key, value)) = &change.mitigation_config {
+                let config = PyDict::new(py);
+                config.set_item("key", key)?;
+                config.set_item("value", value)?;
+                info.set_item("mitigation_config", config)?;
+            }
+            Some(info)
+        }
+        None => None,
+    };
+    let kwargs = PyDict::new(py);
+    kwargs.set_item("classes", &server.classes)?;
+    kwargs.set_item("sql_state", err.sql_state.as_deref())?;
+    kwargs.set_item(
+        "error_class",
+        (!err.error_class.is_empty()).then_some(err.error_class.as_str()),
+    )?;
+    kwargs.set_item("reason", &server.reason)?;
+    kwargs.set_item("message", &err.message)?;
+    // In the order that the server gave the parameters, as the reference 
client keeps it.
+    let parameters = PyDict::new(py);
+    for name in &server.parameter_order {
+        if let Some(value) = err.params.get(name) {
+            parameters.set_item(name, value)?;
+        }
+    }
+    for (name, value) in &err.params {
+        if !parameters.contains(name)? {
+            parameters.set_item(name, value)?;
+        }
+    }
+    kwargs.set_item("message_parameters", parameters)?;
+    kwargs.set_item("stacktrace", err.server_stacktrace.as_deref())?;
+    kwargs.set_item("display_server_stacktrace", server.display_stacktrace)?;
+    kwargs.set_item("contexts", contexts)?;
+    // A server error always comes from a gRPC status; UNKNOWN is the 
reference default.
+    kwargs.set_item("grpc_status_code", err.grpc_code.unwrap_or(2))?;
+    kwargs.set_item("breaking_change_info", breaking_change)?;
+    py.import("pyspark.errors.exceptions.connect")?.call_method(
+        "_convert_server_error",
+        (),
+        Some(&kwargs),
+    )
+}
+
 /// Maps a SparkError to a Python exception, attempting to raise the correct 
typed
 /// exception based on the error kind. Falls back to PyRuntimeError if import 
fails.
 pub fn spark_error_to_py_exception(err: SparkError) -> PyErr {
@@ -60,6 +135,15 @@ pub fn spark_error_to_py_exception(err: SparkError) -> 
PyErr {
 
     // Try to acquire the GIL and import the exception class from 
pyspark.errors
     Python::attach(|py| {
+        if let Some(server) = &err.server {
+            // Should the connect classes not import, fall back to the class 
by kind below.
+            if let Ok(exc_instance) = server_error_to_py(py, &err, server) {
+                if let Some(op) = &operation_id {
+                    let _ = exc_instance.setattr("_operation_id", op);
+                }
+                return PyErr::from_value(exc_instance);
+            }
+        }
         // First, verify and get the exception class from pyspark.errors
         let errors_module = match py.import("pyspark.errors") {
             Ok(m) => m,
diff --git a/crates/spark-connect-core/Cargo.toml 
b/crates/spark-connect-core/Cargo.toml
index a8b61d0..3256bca 100644
--- a/crates/spark-connect-core/Cargo.toml
+++ b/crates/spark-connect-core/Cargo.toml
@@ -22,6 +22,7 @@ bytes.workspace = true
 thiserror.workspace = true
 uuid.workspace = true
 tracing.workspace = true
+serde = "1"
 serde_json = "1"
 regex = "1"
 prost-types.workspace = true
diff --git a/crates/spark-connect-core/src/client.rs 
b/crates/spark-connect-core/src/client.rs
index 0c8c88b..03b94af 100644
--- a/crates/spark-connect-core/src/client.rs
+++ b/crates/spark-connect-core/src/client.rs
@@ -55,6 +55,7 @@ async fn wait_ready(grpc: &mut tonic::client::Grpc<Channel>) 
-> Result<()> {
 /// A Spark Connect client for communicating with a remote Spark server.
 ///
 /// Mirrors `pyspark.sql.connect.client.core.SparkConnectClient`.
+#[derive(Clone)]
 pub struct SparkConnectClient {
     /// The tonic gRPC channel.
     channel: Channel,
@@ -205,9 +206,10 @@ impl SparkConnectClient {
     ) -> Result<Streaming<ExecutePlanResponse>> {
         let mut req = Request::new(request);
         self._attach_metadata(&mut req);
-        let resp = self.stub.clone().execute_plan(req).await;
-        resp.map(Response::into_inner)
-            .map_err(SparkError::from_grpc_status)
+        match self.stub.clone().execute_plan(req).await {
+            Ok(response) => Ok(response.into_inner()),
+            Err(status) => Err(self.error_from_status(status).await),
+        }
     }
 
     /// Execute a plan, forwarding raw request bytes and returning a raw 
response stream.
@@ -259,9 +261,10 @@ impl SparkConnectClient {
     ) -> Result<Streaming<ExecutePlanResponse>> {
         let mut req = Request::new(request);
         self._attach_metadata(&mut req);
-        let resp = self.stub.clone().reattach_execute(req).await;
-        resp.map(Response::into_inner)
-            .map_err(SparkError::from_grpc_status)
+        match self.stub.clone().reattach_execute(req).await {
+            Ok(response) => Ok(response.into_inner()),
+            Err(status) => Err(self.error_from_status(status).await),
+        }
     }
 
     /// Release a (portion of a) running execution's response stream.
@@ -273,9 +276,10 @@ impl SparkConnectClient {
     ) -> Result<ReleaseExecuteResponse> {
         let mut req = Request::new(request);
         self._attach_metadata(&mut req);
-        let resp = self.stub.clone().release_execute(req).await;
-        resp.map(Response::into_inner)
-            .map_err(SparkError::from_grpc_status)
+        match self.stub.clone().release_execute(req).await {
+            Ok(response) => Ok(response.into_inner()),
+            Err(status) => Err(self.error_from_status(status).await),
+        }
     }
 
     /// Analyze a plan, forwarding the raw request bytes without decoding them.
@@ -336,7 +340,7 @@ impl SparkConnectClient {
                             continue;
                         }
                     }
-                    return Err(SparkError::from_grpc_status(status));
+                    return Err(self.error_from_status(status).await);
                 }
             }
         }
@@ -365,10 +369,7 @@ impl SparkConnectClient {
             .map_err(|e| e.with_operation_id(iter.operation_id()))?;
         let retry_policy = self.retry_policy.clone();
         Ok(ReattachableResponseStream {
-            stub: self.stub.clone(),
-            user_agent: self.user_agent.clone(),
-            user_id: self.user_id.clone(),
-            metadata: self.metadata.clone(),
+            client: self.clone(),
             retry_state: RetryPolicyState::new(retry_policy.clone()),
             retry_policy,
             iter,
@@ -393,6 +394,83 @@ impl SparkConnectClient {
             .map_err(SparkError::from_grpc_status)
     }
 
+    /// The error for a failed RPC, as `SparkConnectClient._handle_rpc_error` 
raises it. An
+    /// error that the server raised gets the details that `FetchErrorDetails` 
returns when the
+    /// server keeps them, and shows the server's stack trace when
+    /// `spark.sql.connect.serverStacktrace.enabled` or 
`spark.sql.pyspark.jvmStacktrace.enabled`
+    /// is true. As the error is raised either way, failing to read those is 
not.
+    pub async fn error_from_status(&self, status: tonic::Status) -> SparkError 
{
+        let error = SparkError::from_grpc_status(status);
+        let Some(server) = &error.server else {
+            return error;
+        };
+        let details = match &server.error_id {
+            Some(error_id) => self.error_details(error_id).await,
+            None => None,
+        };
+        let display_stacktrace = self.display_server_stacktrace().await;
+        error.with_details(details, display_stacktrace)
+    }
+
+    /// The details of the error that the server keeps under `error_id`, or 
`None` if they
+    /// cannot be fetched. Mirrors `SparkConnectClient._fetch_enriched_error`.
+    async fn error_details(&self, error_id: &str) -> 
Option<FetchErrorDetailsResponse> {
+        let request = FetchErrorDetailsRequest {
+            session_id: self.session_id.clone(),
+            error_id: error_id.to_string(),
+            client_type: Some(self.user_agent.clone()),
+            user_context: self.user_id.as_ref().map(|user_id| UserContext {
+                user_id: user_id.clone(),
+                ..Default::default()
+            }),
+            ..Default::default()
+        };
+        let mut req = Request::new(request);
+        self._attach_metadata(&mut req);
+        let response = self.stub.clone().fetch_error_details(req).await.ok()?;
+        Some(response.into_inner())
+    }
+
+    /// Whether the message of an error that the server raised shows the 
server's stack
+    /// trace. Mirrors `SparkConnectClient._display_server_stack_trace`, which 
shows it when a
+    /// config cannot be read.
+    async fn display_server_stacktrace(&self) -> bool {
+        match self
+            .conf_while_raising("spark.sql.connect.serverStacktrace.enabled")
+            .await
+        {
+            Some(enabled) if enabled == "true" => true,
+            Some(_) => self
+                .conf_while_raising("spark.sql.pyspark.jvmStacktrace.enabled")
+                .await
+                .is_none_or(|enabled| enabled == "true"),
+            None => true,
+        }
+    }
+
+    /// The value of a config, or `None` if it cannot be read. Read once, 
while an error is
+    /// raised, so that a failure is neither retried nor raised.
+    async fn conf_while_raising(&self, key: &str) -> Option<String> {
+        use spark_connect_proto::config_request::{operation::OpType, Get, 
Operation};
+        let request = ConfigRequest {
+            session_id: self.session_id.clone(),
+            user_context: Some(UserContext {
+                user_id: self.user_id.clone().unwrap_or_default(),
+                ..Default::default()
+            }),
+            operation: Some(Operation {
+                op_type: Some(OpType::Get(Get {
+                    keys: vec![key.to_string()],
+                })),
+            }),
+            ..Default::default()
+        };
+        let mut req = Request::new(request);
+        self._attach_metadata(&mut req);
+        let response = self.stub.clone().config(req).await.ok()?.into_inner();
+        response.pairs.into_iter().next()?.value
+    }
+
     /// Update or fetch configurations.
     ///
     /// Mirrors `pyspark.sql.connect.client.core.SparkConnectClient.config`.
@@ -679,8 +757,10 @@ impl SparkConnectClient {
 
         let mut req = Request::new(request);
         self._attach_metadata(&mut req);
-        let resp = self.stub.clone().release_session(req).await;
-        resp.map(|_| ()).map_err(SparkError::from_grpc_status)
+        match self.stub.clone().release_session(req).await {
+            Ok(_) => Ok(()),
+            Err(status) => Err(self.error_from_status(status).await),
+        }
     }
 
     /// Add artifacts to this session.
@@ -815,13 +895,10 @@ impl SparkConnectClient {
     ) -> Result<()> {
         let mut req = Request::new(requests);
         self._attach_metadata(&mut req);
-        let response = self
-            .stub
-            .clone()
-            .add_artifacts(req)
-            .await
-            .map_err(SparkError::from_grpc_status)?
-            .into_inner();
+        let response = match self.stub.clone().add_artifacts(req).await {
+            Ok(response) => response.into_inner(),
+            Err(status) => return Err(self.error_from_status(status).await),
+        };
         let mut received = std::collections::HashSet::new();
         for summary in response.artifacts {
             if !summary.is_crc_successful {
@@ -861,13 +938,10 @@ impl SparkConnectClient {
 
         let mut req = Request::new(request);
         self._attach_metadata(&mut req);
-        let response = self
-            .stub
-            .clone()
-            .artifact_status(req)
-            .await
-            .map_err(SparkError::from_grpc_status)?
-            .into_inner();
+        let response = match self.stub.clone().artifact_status(req).await {
+            Ok(response) => response.into_inner(),
+            Err(status) => return Err(self.error_from_status(status).await),
+        };
 
         // Build map of artifact name -> exists status
         let mut result = std::collections::HashMap::new();
@@ -920,10 +994,8 @@ impl SparkConnectClient {
 /// server does not keep them until the execution is abandoned. Mirrors
 /// 
`pyspark.sql.connect.client.reattach.ExecutePlanResponseReattachableIterator`.
 pub struct ReattachableResponseStream {
-    stub: SparkConnectServiceClient<Channel>,
-    user_agent: String,
-    user_id: Option<String>,
-    metadata: Vec<(String, String)>,
+    /// The client that started the execution, whose stub, headers and session 
it uses.
+    client: SparkConnectClient,
     retry_policy: RetryPolicy,
     retry_state: RetryPolicyState,
     iter: ExecutePlanResponseReattachableIterator,
@@ -937,15 +1009,15 @@ impl ReattachableResponseStream {
     /// The gRPC metadata of every request about this execution.
     fn metadata_map(&self) -> MetadataMap {
         let mut metadata = MetadataMap::new();
-        if let Ok(v) = MetadataValue::from_str(&self.user_agent) {
+        if let Ok(v) = MetadataValue::from_str(&self.client.user_agent) {
             let _ = metadata.insert("user-agent", v);
         }
-        if let Some(user_id) = &self.user_id {
+        if let Some(user_id) = &self.client.user_id {
             if let Ok(v) = MetadataValue::from_str(user_id) {
                 let _ = metadata.insert("user_id", v);
             }
         }
-        for (k, v) in &self.metadata {
+        for (k, v) in &self.client.metadata {
             if let Ok(v) = MetadataValue::from_str(v) {
                 if let Ok(key) = 
tonic::metadata::MetadataKey::from_bytes(k.as_bytes()) {
                     let _ = metadata.insert(key, v);
@@ -984,7 +1056,8 @@ impl ReattachableResponseStream {
                 Err(status) => {
                     // Only reattach a still-running execution on a retriable 
drop.
                     if self.iter.is_completed().await || 
!self.retry_policy.can_retry(&status) {
-                        return 
Err(self.fail(SparkError::from_grpc_status(status)));
+                        let error = 
self.client.error_from_status(status).await;
+                        return Err(self.fail(error));
                     }
                     self.reattach().await?;
                 }
@@ -997,7 +1070,7 @@ impl ReattachableResponseStream {
         loop {
             let mut req = 
Request::new(self.iter.create_reattach_request().await);
             self.attach_metadata(&mut req);
-            match self.stub.reattach_execute(req).await {
+            match self.client.stub.clone().reattach_execute(req).await {
                 Ok(r) => {
                     self.stream = r.into_inner();
                     return Ok(());
@@ -1009,7 +1082,8 @@ impl ReattachableResponseStream {
                             continue;
                         }
                     }
-                    return Err(self.fail(SparkError::from_grpc_status(e)));
+                    let error = self.client.error_from_status(e).await;
+                    return Err(self.fail(error));
                 }
             }
         }
@@ -1044,7 +1118,7 @@ impl ReattachableResponseStream {
     /// removes an execution that is never released once it has been detached 
for
     /// `spark.connect.execute.manager.detachedTimeout`.
     fn spawn_release(&self, request: ReleaseExecuteRequest) {
-        let mut stub = self.stub.clone();
+        let mut stub = self.client.stub.clone();
         let metadata = self.metadata_map();
         let policy = self.retry_policy.clone();
         let release = async move {
diff --git a/crates/spark-connect-core/src/error.rs 
b/crates/spark-connect-core/src/error.rs
index c0f0a73..e86cfbc 100644
--- a/crates/spark-connect-core/src/error.rs
+++ b/crates/spark-connect-core/src/error.rs
@@ -151,6 +151,40 @@ struct RpcErrorInfo {
     metadata: HashMap<String, String>,
 }
 
+/// What a server error carries besides its message, condition, parameters, 
SQL state, stack
+/// trace and query contexts, as PySpark Connect reads it from the error's 
`ErrorInfo` and, when
+/// the server keeps more, from `FetchErrorDetails`.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct ServerErrorInfo {
+    /// The JVM class of the exception and then its superclasses (`classes`).
+    pub classes: Vec<String>,
+    /// `ErrorInfo.reason`.
+    pub reason: String,
+    /// The id that the server keeps the error's details under (`errorId`), if 
it keeps them.
+    pub error_id: Option<String>,
+    /// The names of the message parameters in the order that the server gave 
them, which the
+    /// reference client keeps.
+    pub parameter_order: Vec<String>,
+    /// Whether the message shows the server's stack trace, as
+    /// `spark.sql.connect.serverStacktrace.enabled` or 
`spark.sql.pyspark.jvmStacktrace.enabled`
+    /// decides.
+    pub display_stacktrace: bool,
+    /// The breaking change that the error comes from, if the server reports 
one.
+    pub breaking_change: Option<BreakingChangeInfo>,
+}
+
+/// A breaking change that an error comes from. Mirrors what
+/// `SparkConnectGrpcException.getBreakingChangeInfo()` returns.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct BreakingChangeInfo {
+    /// How to migrate.
+    pub migration_message: Vec<String>,
+    /// The config, as a key and a value, that restores the previous behavior.
+    pub mitigation_config: Option<(String, String)>,
+    /// Whether the change needs an audit.
+    pub needs_audit: bool,
+}
+
 /// A structured error carrying a PySpark error class and its message 
parameters.
 #[derive(Debug, Clone)]
 pub struct SparkError {
@@ -176,6 +210,9 @@ pub struct SparkError {
     /// The ExecutePlan operation id the error was raised for, if known. Backs
     /// `SparkConnectException.operation_id` (new in pyspark 4.3.0).
     pub operation_id: Option<String>,
+    /// For an error that the server raised, what it sent about it besides the 
fields above.
+    /// Boxed, so that it does not make every `Result` larger.
+    pub server: Option<Box<ServerErrorInfo>>,
 }
 
 /// The PySpark exception hierarchy leaf we map to.
@@ -248,6 +285,8 @@ pub enum SparkErrorKind {
     InvalidPlanInput,
     /// ``pyspark.errors.exceptions.connect.PickleException``
     PickleException,
+    /// ``pyspark.errors.exceptions.connect.SparkException``
+    Spark,
 }
 
 impl SparkError {
@@ -269,6 +308,7 @@ impl SparkError {
             grpc_code: None,
             grpc_details: None,
             operation_id: None,
+            server: None,
         }
     }
 
@@ -290,6 +330,7 @@ impl SparkError {
             grpc_code: None,
             grpc_details: None,
             operation_id: None,
+            server: None,
         }
     }
 
@@ -309,6 +350,7 @@ impl SparkError {
             grpc_code: None,
             grpc_details: None,
             operation_id: None,
+            server: None,
         }
     }
 
@@ -316,11 +358,12 @@ impl SparkError {
     ///
     /// If an error_class is set, looks up the message template in 
error-conditions.json,
     /// substitutes `<param_name>` placeholders with values from `params`, and 
returns
-    /// `[ERROR_CLASS] rendered_message`. Otherwise, returns the pre-set 
message.
+    /// `[ERROR_CLASS] rendered_message`. Otherwise, returns the pre-set 
message. The message
+    /// of an error that the server raised is the server's, which already 
names the condition.
     ///
     /// Mirrors `PySparkException.getMessage()` from 
`pyspark/errors/exceptions/base.py`.
     pub fn message(&self) -> String {
-        if self.error_class.is_empty() {
+        if self.error_class.is_empty() || self.server.is_some() {
             return self.message.clone();
         }
 
@@ -348,35 +391,20 @@ impl SparkError {
         }
     }
 
-    /// Convert a gRPC Status to a SparkError, extracting error class and 
parameters from metadata.
+    /// Convert a gRPC Status to a SparkError.
     ///
-    /// Mirrors `convert_exception` from `pyspark.errors.exceptions.connect`.
+    /// A status with an `ErrorInfo` is an error that the server raised. As
+    /// `pyspark.errors.exceptions.connect.convert_exception` does, its 
exception classes,
+    /// condition, message parameters, SQL state and stack trace are read from 
the
+    /// `ErrorInfo`, and its kind from the classes. 
[`SparkError::with_details`] completes it
+    /// with what `FetchErrorDetails` returns.
     pub fn from_grpc_status(status: Status) -> Self {
-        // Extract error metadata from trailer if present
         let message = status.message().to_string();
         let code = status.code() as i32;
-
-        // Try to parse details from the Status (details is a byte slice)
         let details = status.details().to_vec();
-        let mut err = if details.is_empty() {
-            Self::connect_msg(format!("[{}] {}", status.code(), message))
-        } else {
-            // Decode grpc-status-details-bin as a google.rpc.Status with 
Any-packed ErrorInfo.
-            match parse_error_info_from_details(&details) {
-                Some((error_class, params, sql_state, server_stacktrace)) => 
Self {
-                    kind: classify_error_kind_with_classes(&error_class, 
&params),
-                    error_class,
-                    params,
-                    message,
-                    sql_state,
-                    contexts: Vec::new(),
-                    server_stacktrace,
-                    grpc_code: None,
-                    grpc_details: None,
-                    operation_id: None,
-                },
-                None => Self::connect_msg(format!("[{}] {}", status.code(), 
message)),
-            }
+        let mut err = match parse_error_info(&details) {
+            Some(info) => Self::from_error_info(info, message),
+            None => Self::connect_msg(format!("[{}] {}", status.code(), 
message)),
         };
         // Preserve the raw status so the PyO3 layer can rebuild the exact 
pyspark exception.
         err.grpc_code = Some(code);
@@ -386,6 +414,120 @@ impl SparkError {
         err
     }
 
+    /// An error that the server raised, from its `ErrorInfo`.
+    fn from_error_info(info: RpcErrorInfo, message: String) -> Self {
+        let mut metadata = info.metadata;
+        let classes = metadata
+            .get("classes")
+            .and_then(|classes| serde_json::from_str(classes).ok())
+            .unwrap_or_default();
+        let params = metadata
+            .get("messageParameters")
+            .and_then(|params| serde_json::from_str(params).ok())
+            .unwrap_or_default();
+        let parameter_order = metadata
+            .get("messageParameters")
+            .map(|params| parameter_names(params))
+            .unwrap_or_default();
+        let mut err = Self {
+            kind: SparkErrorKind::Unknown,
+            error_class: metadata.remove("errorClass").unwrap_or_default(),
+            params,
+            message,
+            sql_state: metadata.remove("sqlState"),
+            contexts: Vec::new(),
+            server_stacktrace: metadata.remove("stackTrace"),
+            grpc_code: None,
+            grpc_details: None,
+            operation_id: None,
+            server: Some(Box::new(ServerErrorInfo {
+                classes,
+                reason: info.reason,
+                error_id: metadata.remove("errorId"),
+                parameter_order,
+                ..Default::default()
+            })),
+        };
+        err.kind = err.server_kind();
+        err
+    }
+
+    /// Completes an error that the server raised, as
+    /// `pyspark.errors.exceptions.connect._convert_exception` does: with the 
error's details
+    /// as `FetchErrorDetails` returned them, if it did, and whether the 
message shows the
+    /// server's stack trace. Without the details, the message shows the stack 
trace only if
+    /// the `ErrorInfo` had one. Any other error is returned as is.
+    pub fn with_details(
+        mut self,
+        details: Option<spark_connect_proto::FetchErrorDetailsResponse>,
+        display_stacktrace: bool,
+    ) -> Self {
+        if self.server.is_none() {
+            return self;
+        }
+        let root = details.and_then(|details| {
+            let index = usize::try_from(details.root_error_idx?).ok()?;
+            (index < details.errors.len()).then_some((index, details.errors))
+        });
+        let display_stacktrace = match root {
+            Some((index, errors)) => {
+                let root = &errors[index];
+                self.message = root.message.clone();
+                self.server_stacktrace = Some(jvm_stacktrace(index, &errors));
+                let throwable = 
root.spark_throwable.clone().unwrap_or_default();
+                if self.error_class.is_empty() {
+                    if let Some(error_class) = throwable.error_class {
+                        self.error_class = error_class;
+                    }
+                }
+                self.params = 
throwable.message_parameters.into_iter().collect();
+                self.contexts = throwable
+                    .query_contexts
+                    .into_iter()
+                    .map(QueryContext::from)
+                    .collect();
+                if let Some(server) = self.server.as_mut() {
+                    server.breaking_change =
+                        
throwable.breaking_change_info.map(BreakingChangeInfo::from);
+                }
+                display_stacktrace
+            }
+            None => {
+                display_stacktrace
+                    && self
+                        .server_stacktrace
+                        .as_deref()
+                        .is_some_and(|stacktrace| !stacktrace.is_empty())
+            }
+        };
+        if let Some(server) = self.server.as_mut() {
+            server.display_stacktrace = display_stacktrace;
+        }
+        self.kind = self.server_kind();
+        self
+    }
+
+    /// The kind of an error that the server raised, from its exception 
classes. As
+    /// `_convert_exception` picks the exception, the first class, from the 
most specific one,
+    /// that `EXCEPTION_CLASS_MAPPING` maps decides it, and an error with none 
is unknown.
+    fn server_kind(&self) -> SparkErrorKind {
+        let classes = self
+            .server
+            .as_ref()
+            .map(|server| server.classes.as_slice())
+            .unwrap_or_default();
+        if classes
+            .iter()
+            .any(|class| class == 
"org.apache.spark.api.python.PythonException")
+        {
+            return SparkErrorKind::Python;
+        }
+        classes
+            .iter()
+            .find_map(|class| exception_class_kind(class, &self.message))
+            .unwrap_or(SparkErrorKind::Unknown)
+    }
+
     /// Attach the ExecutePlan operation id this error was raised for.
     pub fn with_operation_id(mut self, operation_id: impl Into<String>) -> 
Self {
         self.operation_id = Some(operation_id.into());
@@ -478,123 +620,153 @@ pub type Result<T> = std::result::Result<T, SparkError>;
 // gRPC error detail parsing
 // ============================================================================
 
-/// Parse ErrorInfo from gRPC status details bytes.
-///
-/// Expects the details to be a protobuf-encoded google.rpc.Status containing
-/// Any-packed google.rpc.ErrorInfo messages. Returns (error_class, params, 
sql_state, stacktrace) if found.
-fn parse_error_info_from_details(
-    details: &[u8],
-) -> Option<(
-    String,
-    BTreeMap<String, String>,
-    Option<String>,
-    Option<String>,
-)> {
-    // Decode the outer google.rpc.Status from details
-    let rpc_status = RpcStatus::decode(details).ok()?;
-
-    // Look for an ErrorInfo in the details list
-    for any_detail in &rpc_status.details {
-        // google.rpc.ErrorInfo type URL
-        if any_detail.type_url == "type.googleapis.com/google.rpc.ErrorInfo" {
-            // Decode the Any.value as google.rpc.ErrorInfo
-            if let Ok(error_info) = 
RpcErrorInfo::decode(&any_detail.value[..]) {
-                // Extract errorClass and other metadata
-                let error_class = error_info
-                    .metadata
-                    .get("errorClass")
-                    .cloned()
-                    .unwrap_or_else(|| error_info.reason.clone());
-
-                let sql_state = error_info.metadata.get("sqlState").cloned();
-                let stacktrace = 
error_info.metadata.get("stackTrace").cloned();
-
-                // Convert HashMap to BTreeMap
-                let params: BTreeMap<String, String> = error_info
-                    .metadata
-                    .iter()
-                    .map(|(k, v)| (k.clone(), v.clone()))
-                    .collect();
+/// The `google.rpc.ErrorInfo` of a gRPC status, from its 
`grpc-status-details-bin`: the
+/// protobuf-encoded `google.rpc.Status` whose details hold Any-packed 
messages.
+fn parse_error_info(details: &[u8]) -> Option<RpcErrorInfo> {
+    if details.is_empty() {
+        return None;
+    }
+    RpcStatus::decode(details)
+        .ok()?
+        .details
+        .into_iter()
+        .filter(|detail| detail.type_url == 
"type.googleapis.com/google.rpc.ErrorInfo")
+        .find_map(|detail| RpcErrorInfo::decode(&detail.value[..]).ok())
+}
 
-                // Return the parsed error info
-                return Some((error_class, params, sql_state, stacktrace));
+/// The names in a JSON object of message parameters, in their order. A JSON 
object that does
+/// not parse has none.
+fn parameter_names(json: &str) -> Vec<String> {
+    struct Names(Vec<String>);
+    impl<'de> serde::Deserialize<'de> for Names {
+        fn deserialize<D: serde::Deserializer<'de>>(
+            deserializer: D,
+        ) -> std::result::Result<Self, D::Error> {
+            struct NamesVisitor;
+            impl<'de> serde::de::Visitor<'de> for NamesVisitor {
+                type Value = Names;
+                fn expecting(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result 
{
+                    f.write_str("a JSON object")
+                }
+                fn visit_map<A: serde::de::MapAccess<'de>>(
+                    self,
+                    mut map: A,
+                ) -> std::result::Result<Names, A::Error> {
+                    let mut names = Vec::new();
+                    while let Some((name, _)) = map.next_entry::<String, 
serde::de::IgnoredAny>()? {
+                        names.push(name);
+                    }
+                    Ok(Names(names))
+                }
             }
+            deserializer.deserialize_map(NamesVisitor)
         }
     }
+    serde_json::from_str::<Names>(json)
+        .map(|names| names.0)
+        .unwrap_or_default()
+}
 
-    None
+/// The kind of the exception that a JVM exception class maps to, as
+/// `pyspark.errors.exceptions.connect.EXCEPTION_CLASS_MAPPING` and
+/// `THIRD_PARTY_EXCEPTION_CLASS_MAPPING` map it, or `None` for a class that 
they do not map.
+fn exception_class_kind(class: &str, message: &str) -> Option<SparkErrorKind> {
+    use SparkErrorKind::*;
+    Some(match class {
+        "org.apache.spark.sql.catalyst.parser.ParseException" => Parse,
+        "org.apache.spark.sql.AnalysisException" => Analysis,
+        "org.apache.spark.sql.streaming.StreamingQueryException" => 
StreamingQuery,
+        "org.apache.spark.sql.execution.QueryExecutionException" => 
QueryExecution,
+        "java.lang.NumberFormatException" => NumberFormat,
+        "java.lang.IllegalArgumentException" => IllegalArgument,
+        "java.lang.ArithmeticException" => Arithmetic,
+        "java.lang.UnsupportedOperationException" => UnsupportedOperation,
+        "java.lang.ArrayIndexOutOfBoundsException" => ArrayIndexOutOfBounds,
+        "java.time.DateTimeException" => DateTime,
+        "org.apache.spark.SparkRuntimeException" => SparkRuntime,
+        "org.apache.spark.SparkUpgradeException" => SparkUpgrade,
+        "org.apache.spark.api.python.PythonException" => Python,
+        "org.apache.spark.SparkNoSuchElementException" => SparkNoSuchElement,
+        // A SparkException from a failure to pickle on the server.
+        "org.apache.spark.SparkException" if 
message.contains("net.razorvine.pickle.PickleException") => {
+            PickleException
+        }
+        "org.apache.spark.SparkException" => Spark,
+        "org.apache.spark.sql.connect.common.InvalidPlanInput" => 
InvalidPlanInput,
+        
"org.apache.spark.api.python.StreamingPythonRunner$StreamingPythonRunnerInitializationException"
 => {
+            StreamingPythonRunnerInitialization
+        }
+        _ => return None,
+    })
 }
 
-/// Classify a server error into a `SparkErrorKind`, preferring the JVM 
exception-class
-/// hierarchy (the `classes` metadata, e.g. 
`["org.apache.spark.sql.AnalysisException",…]`)
-/// over the error-condition name. Spark's analysis errors are named 
`UNRESOLVED_COLUMN`,
-/// `TABLE_OR_VIEW_NOT_FOUND`, … — none start with "ANALYSIS" — so classifying 
by the
-/// condition string alone mislabels them as generic runtime errors and breaks
-/// `except AnalysisException:`.
-fn classify_error_kind_with_classes(
-    error_class: &str,
-    params: &BTreeMap<String, String>,
-) -> SparkErrorKind {
-    if let Some(classes) = params.get("classes") {
-        // Most-specific first; the string holds the whole hierarchy.
-        let checks: &[(&str, SparkErrorKind)] = &[
-            ("AnalysisException", SparkErrorKind::Analysis),
-            ("ParseException", SparkErrorKind::Parse),
-            ("StreamingQueryException", SparkErrorKind::StreamingQuery),
-            ("SparkUpgradeException", SparkErrorKind::SparkUpgrade),
-            ("NumberFormatException", SparkErrorKind::NumberFormat),
-            (
-                "ArrayIndexOutOfBoundsException",
-                SparkErrorKind::ArrayIndexOutOfBounds,
-            ),
-            ("DateTimeException", SparkErrorKind::DateTime),
-            ("ArithmeticException", SparkErrorKind::Arithmetic),
-            (
-                "UnsupportedOperationException",
-                SparkErrorKind::UnsupportedOperation,
-            ),
-            ("IllegalArgumentException", SparkErrorKind::IllegalArgument),
-            ("NoSuchElementException", SparkErrorKind::SparkNoSuchElement),
-            ("PythonException", SparkErrorKind::Python),
-            ("SparkRuntimeException", SparkErrorKind::SparkRuntime),
-        ];
-        for (needle, kind) in checks {
-            if classes.contains(needle) {
-                return *kind;
-            }
+/// The JVM stack trace of the error at `index` in `FetchErrorDetails`' 
errors, with its
+/// causes. Mirrors 
`pyspark.errors.exceptions.connect._extract_jvm_stacktrace`.
+fn jvm_stacktrace(
+    index: usize,
+    errors: &[spark_connect_proto::fetch_error_details_response::Error],
+) -> String {
+    let mut lines: Vec<String> = Vec::new();
+    let mut next = Some(index);
+    // A cause is another error of the list; stop at a cycle.
+    let mut seen = std::collections::HashSet::new();
+    while let Some(error) = next.filter(|i| seen.insert(*i)).and_then(|i| 
errors.get(i)) {
+        let class = error
+            .error_type_hierarchy
+            .first()
+            .map(String::as_str)
+            .unwrap_or_default();
+        if lines.is_empty() {
+            lines.push(class.to_string());
+        } else {
+            lines.push(format!("Caused by: {}: {}", class, error.message));
         }
+        for element in &error.stack_trace {
+            lines.push(format!(
+                "\tat {}.{}({}:{})",
+                element.declaring_class,
+                element.method_name,
+                element.file_name.as_deref().unwrap_or_default(),
+                element.line_number
+            ));
+        }
+        next = error.cause_idx.and_then(|i| usize::try_from(i).ok());
     }
-    classify_error_kind(error_class)
+    lines.join("\n")
 }
 
-/// Classify error_class string into a SparkErrorKind.
-///
-/// Maps Spark error classes to the corresponding Python exception type.
-fn classify_error_kind(error_class: &str) -> SparkErrorKind {
-    if error_class.starts_with("ANALYSIS") {
-        SparkErrorKind::Analysis
-    } else if error_class.starts_with("PARSE") {
-        SparkErrorKind::Parse
-    } else if error_class.starts_with("ILLEGAL") {
-        SparkErrorKind::IllegalArgument
-    } else if error_class.starts_with("UNSUPPORTED") {
-        SparkErrorKind::UnsupportedOperation
-    } else if error_class.starts_with("ARITHMETIC") {
-        SparkErrorKind::Arithmetic
-    } else if error_class.contains("NOT_IMPLEMENTED") {
-        SparkErrorKind::NotImplementedError
-    } else if error_class.contains("RUNTIME") {
-        SparkErrorKind::RuntimeError
-    } else if error_class.contains("VALUE") {
-        SparkErrorKind::ValueError
-    } else {
-        match error_class {
-            "INVALID_CONNECT_URL" => SparkErrorKind::RuntimeError,
-            "SYNTAX_ERROR" => SparkErrorKind::Parse,
-            "INVALID_PLAN_INPUT" => SparkErrorKind::InvalidPlanInput,
-            "PICKLE_ERROR" => SparkErrorKind::PickleException,
-            "RESPONSE_ALREADY_RECEIVED" | "INVALID_HANDLE" => 
SparkErrorKind::ConnectGrpc,
-            _ => SparkErrorKind::RuntimeError, // Default fallback
+impl From<spark_connect_proto::fetch_error_details_response::QueryContext> for 
QueryContext {
+    fn from(context: 
spark_connect_proto::fetch_error_details_response::QueryContext) -> Self {
+        use 
spark_connect_proto::fetch_error_details_response::query_context::ContextType;
+        let context_type = if context.context_type == ContextType::Dataframe 
as i32 {
+            QueryContextType::DataFrame
+        } else {
+            QueryContextType::SQL
+        };
+        QueryContext::new(
+            context_type,
+            context.object_type,
+            context.object_name,
+            context.start_index,
+            context.stop_index,
+            context.fragment,
+            context.call_site,
+            context.summary,
+        )
+    }
+}
+
+impl 
From<spark_connect_proto::fetch_error_details_response::BreakingChangeInfo>
+    for BreakingChangeInfo
+{
+    fn from(info: 
spark_connect_proto::fetch_error_details_response::BreakingChangeInfo) -> Self {
+        BreakingChangeInfo {
+            migration_message: info.migration_message,
+            mitigation_config: info
+                .mitigation_config
+                .map(|config| (config.key, config.value)),
+            // As in pyspark, a change that does not say needs an audit.
+            needs_audit: info.needs_audit.unwrap_or(true),
         }
     }
 }
@@ -964,81 +1136,344 @@ mod tests {
         );
     }
 
-    #[test]
-    fn test_parse_error_info_from_grpc_status() {
-        // Create a synthetic google.rpc.ErrorInfo
-        let mut error_metadata = HashMap::new();
-        error_metadata.insert("errorClass".to_string(), 
"ANALYSIS_ERROR".to_string());
-        error_metadata.insert("sqlState".to_string(), "42601".to_string());
-        error_metadata.insert(
-            "messageParameters".to_string(),
-            r#"{"message":"test error"}"#.to_string(),
-        );
-        error_metadata.insert(
-            "stackTrace".to_string(),
-            "at org.apache.spark.sql....".to_string(),
-        );
-
+    /// A gRPC status of an error that the server raised, with an `ErrorInfo` 
of `metadata`.
+    fn server_status(message: &str, metadata: &[(&str, &str)]) -> Status {
         let error_info = RpcErrorInfo {
-            reason: "ANALYSIS_ERROR".to_string(),
-            domain: "org.apache.spark.connect".to_string(),
-            metadata: error_metadata,
-        };
-
-        // Pack into Any
-        let error_info_bytes = error_info.encode_to_vec();
-        let any = RpcAny {
-            type_url: "type.googleapis.com/google.rpc.ErrorInfo".to_string(),
-            value: error_info_bytes,
+            reason: 
"org.apache.spark.sql.catalyst.parser.ParseException".to_string(),
+            domain: "org.apache.spark".to_string(),
+            metadata: metadata
+                .iter()
+                .map(|(k, v)| (k.to_string(), v.to_string()))
+                .collect(),
         };
-
-        // Create outer Status
-        let rpc_status = RpcStatus {
-            code: 0,
-            message: "Analysis error".to_string(),
-            details: vec![any],
+        let status = RpcStatus {
+            code: tonic::Code::Internal as i32,
+            message: message.to_string(),
+            details: vec![RpcAny {
+                type_url: 
"type.googleapis.com/google.rpc.ErrorInfo".to_string(),
+                value: error_info.encode_to_vec(),
+            }],
         };
+        Status::with_details(
+            tonic::Code::Internal,
+            message,
+            bytes::Bytes::from(status.encode_to_vec()),
+        )
+    }
 
-        let status_bytes = rpc_status.encode_to_vec();
+    fn classes(classes: &[&str]) -> String {
+        serde_json::to_string(classes).unwrap()
+    }
 
-        // Parse it back
-        let result = parse_error_info_from_details(&status_bytes);
-        assert!(result.is_some());
+    #[test]
+    fn a_server_error_reads_its_error_info() {
+        let message = "\n[PARSE_SYNTAX_ERROR] Syntax error at or near 'SELEC'. 
SQLSTATE: 42601";
+        let err = SparkError::from_grpc_status(server_status(
+            message,
+            &[
+                (
+                    "classes",
+                    &classes(&[
+                        "org.apache.spark.sql.catalyst.parser.ParseException",
+                        "org.apache.spark.sql.AnalysisException",
+                    ]),
+                ),
+                ("errorClass", "PARSE_SYNTAX_ERROR"),
+                ("sqlState", "42601"),
+                ("messageParameters", r#"{"error":"'SELEC'","hint":""}"#),
+                ("errorId", "error-1"),
+            ],
+        ));
+        // A ParseException is also an AnalysisException; the most specific 
class decides.
+        assert_eq!(err.kind, SparkErrorKind::Parse);
+        assert_eq!(err.get_condition().as_deref(), Some("PARSE_SYNTAX_ERROR"));
+        assert_eq!(err.get_sql_state().as_deref(), Some("42601"));
+        // The parameters are the message's, not the rest of the metadata.
+        let params: Vec<_> = err.params.iter().collect();
+        assert_eq!(
+            params,
+            [
+                (&"error".to_string(), &"'SELEC'".to_string()),
+                (&"hint".to_string(), &String::new())
+            ]
+        );
+        // The server's message already names the condition.
+        assert_eq!(err.message(), message);
+        assert_eq!(err.to_string(), message);
+        let server = err.server.as_ref().unwrap();
+        assert_eq!(
+            server.reason,
+            "org.apache.spark.sql.catalyst.parser.ParseException"
+        );
+        assert_eq!(server.error_id.as_deref(), Some("error-1"));
+        assert!(!server.display_stacktrace);
+        assert_eq!(err.grpc_code(), Some(tonic::Code::Internal as i32));
+        assert!(err.grpc_details().is_some());
+    }
 
-        let (error_class, params, sql_state, stacktrace) = result.unwrap();
-        assert_eq!(error_class, "ANALYSIS_ERROR");
-        assert_eq!(sql_state, Some("42601".to_string()));
-        assert_eq!(stacktrace, Some("at 
org.apache.spark.sql....".to_string()));
-        assert!(params.contains_key("errorClass"));
+    #[test]
+    fn a_server_error_keeps_the_order_of_its_parameters() {
+        let err = SparkError::from_grpc_status(server_status(
+            "[INVALID_CONF_VALUE.TYPE_MISMATCH] ...",
+            &[(
+                "messageParameters",
+                
r#"{"confName":"spark.sql.shuffle.partitions","confValue":"abc","confType":"int"}"#,
+            )],
+        ));
+        assert_eq!(
+            err.server.unwrap().parameter_order,
+            ["confName", "confValue", "confType"]
+        );
+        assert!(parameter_names("not json").is_empty());
+        assert!(parameter_names("[1, 2]").is_empty());
     }
 
     #[test]
-    fn test_classify_error_kind() {
+    fn the_first_class_that_maps_decides_the_kind_of_a_server_error() {
+        let kind = |message: &str, hierarchy: &[&str]| {
+            SparkError::from_grpc_status(server_status(
+                message,
+                &[("classes", &classes(hierarchy))],
+            ))
+            .kind
+        };
         assert_eq!(
-            classify_error_kind("ANALYSIS_ERROR"),
+            kind(
+                "x",
+                &[
+                    "org.apache.spark.sql.catalyst.ExtendedAnalysisException",
+                    "org.apache.spark.sql.AnalysisException",
+                    "java.lang.Exception",
+                ]
+            ),
             SparkErrorKind::Analysis
         );
-        assert_eq!(classify_error_kind("PARSE_ERROR"), SparkErrorKind::Parse);
         assert_eq!(
-            classify_error_kind("ILLEGAL_ARGUMENT"),
-            SparkErrorKind::IllegalArgument
+            kind(
+                "x",
+                &[
+                    "org.apache.spark.SparkNumberFormatException",
+                    "java.lang.NumberFormatException",
+                    "java.lang.IllegalArgumentException",
+                ]
+            ),
+            SparkErrorKind::NumberFormat
         );
         assert_eq!(
-            classify_error_kind("ARITHMETIC_ERROR"),
+            kind(
+                "x",
+                &[
+                    "org.apache.spark.SparkArithmeticException",
+                    "java.lang.ArithmeticException"
+                ]
+            ),
             SparkErrorKind::Arithmetic
         );
+        // A PythonException anywhere in the hierarchy decides it.
+        assert_eq!(
+            kind(
+                "x",
+                &[
+                    "org.apache.spark.SparkException",
+                    "org.apache.spark.api.python.PythonException"
+                ]
+            ),
+            SparkErrorKind::Python
+        );
         assert_eq!(
-            classify_error_kind("UNSUPPORTED_OPERATION"),
-            SparkErrorKind::UnsupportedOperation
+            kind("x", &["org.apache.spark.SparkException"]),
+            SparkErrorKind::Spark
         );
         assert_eq!(
-            classify_error_kind("INVALID_PLAN_INPUT"),
+            kind(
+                "net.razorvine.pickle.PickleException: expected zero 
arguments",
+                &["org.apache.spark.SparkException"]
+            ),
+            SparkErrorKind::PickleException
+        );
+        assert_eq!(
+            kind(
+                "x",
+                &["org.apache.spark.sql.connect.common.InvalidPlanInput"]
+            ),
             SparkErrorKind::InvalidPlanInput
         );
         assert_eq!(
-            classify_error_kind("RESPONSE_ALREADY_RECEIVED"),
-            SparkErrorKind::ConnectGrpc
+            kind("x", &["java.lang.IllegalStateException"]),
+            SparkErrorKind::Unknown
         );
+        assert_eq!(kind("x", &[]), SparkErrorKind::Unknown);
+    }
+
+    #[test]
+    fn details_complete_a_server_error() {
+        use spark_connect_proto::fetch_error_details_response::{
+            query_context::ContextType, BreakingChangeInfo as ProtoChange, 
Error, MitigationConfig,
+            QueryContext as ProtoContext, SparkThrowable, StackTraceElement,
+        };
+        use spark_connect_proto::FetchErrorDetailsResponse;
+        let element = |method: &str, file: Option<&str>, line| 
StackTraceElement {
+            declaring_class: "org.apache.spark.Expr".to_string(),
+            method_name: method.to_string(),
+            file_name: file.map(str::to_string),
+            line_number: line,
+        };
+        let details = FetchErrorDetailsResponse {
+            root_error_idx: Some(1),
+            errors: vec![
+                Error {
+                    error_type_hierarchy: 
vec!["java.lang.RuntimeException".to_string()],
+                    message: "the cause".to_string(),
+                    stack_trace: vec![element("cause", Some("Cause.scala"), 
3)],
+                    ..Default::default()
+                },
+                Error {
+                    error_type_hierarchy: vec![
+                        
"org.apache.spark.SparkArithmeticException".to_string(),
+                        "java.lang.ArithmeticException".to_string(),
+                    ],
+                    message: "[DIVIDE_BY_ZERO] Division by zero.".to_string(),
+                    stack_trace: vec![
+                        element("eval", Some("Expr.scala"), 12),
+                        element("native", None, -2),
+                    ],
+                    cause_idx: Some(0),
+                    spark_throwable: Some(SparkThrowable {
+                        error_class: Some("DIVIDE_BY_ZERO".to_string()),
+                        message_parameters: [("config".to_string(), 
"ansi".to_string())].into(),
+                        query_contexts: vec![ProtoContext {
+                            context_type: ContextType::Sql as i32,
+                            fragment: "1/0".to_string(),
+                            start_index: 7,
+                            stop_index: 9,
+                            ..Default::default()
+                        }],
+                        sql_state: Some("22012".to_string()),
+                        breaking_change_info: Some(ProtoChange {
+                            migration_message: vec!["Set the 
config.".to_string()],
+                            mitigation_config: Some(MitigationConfig {
+                                key: "spark.sql.ansi.enabled".to_string(),
+                                value: "false".to_string(),
+                            }),
+                            needs_audit: None,
+                        }),
+                    }),
+                },
+            ],
+            ..Default::default()
+        };
+        // The ErrorInfo has neither a condition nor a stack trace; the 
details have both.
+        let err = SparkError::from_grpc_status(server_status(
+            "[DIVIDE_BY_ZERO] Division by ze...",
+            &[
+                (
+                    "classes",
+                    &classes(&[
+                        "org.apache.spark.SparkArithmeticException",
+                        "java.lang.ArithmeticException",
+                    ]),
+                ),
+                ("errorId", "error-2"),
+            ],
+        ))
+        .with_details(Some(details), true);
+        assert_eq!(err.kind, SparkErrorKind::Arithmetic);
+        assert_eq!(err.message(), "[DIVIDE_BY_ZERO] Division by zero.");
+        assert_eq!(err.get_condition().as_deref(), Some("DIVIDE_BY_ZERO"));
+        assert_eq!(err.params.get("config").map(String::as_str), Some("ansi"));
+        assert_eq!(
+            err.get_stacktrace().as_deref(),
+            Some(
+                "org.apache.spark.SparkArithmeticException\n\
+                 \tat org.apache.spark.Expr.eval(Expr.scala:12)\n\
+                 \tat org.apache.spark.Expr.native(:-2)\n\
+                 Caused by: java.lang.RuntimeException: the cause\n\
+                 \tat org.apache.spark.Expr.cause(Cause.scala:3)"
+            )
+        );
+        let contexts = err.get_query_context();
+        assert_eq!(contexts.len(), 1);
+        assert_eq!(contexts[0].context_type(), QueryContextType::SQL);
+        assert_eq!(contexts[0].fragment(), "1/0");
+        assert_eq!(
+            (contexts[0].start_index(), contexts[0].stop_index()),
+            (7, 9)
+        );
+        let server = err.server.as_ref().unwrap();
+        assert!(server.display_stacktrace);
+        assert_eq!(
+            server.breaking_change,
+            Some(BreakingChangeInfo {
+                migration_message: vec!["Set the config.".to_string()],
+                mitigation_config: Some((
+                    "spark.sql.ansi.enabled".to_string(),
+                    "false".to_string()
+                )),
+                needs_audit: true,
+            })
+        );
+    }
+
+    #[test]
+    fn without_details_a_server_error_shows_a_stack_trace_only_if_it_has_one() 
{
+        let status = |metadata: &[(&str, &str)]| {
+            SparkError::from_grpc_status(server_status("[X] message", 
metadata))
+        };
+        let with_trace = status(&[("stackTrace", "org.apache.spark.X\n\tat 
...")]);
+        let shown = with_trace.clone().with_details(None, true);
+        assert!(shown.server.as_ref().unwrap().display_stacktrace);
+        assert_eq!(shown.message(), "[X] message");
+        assert!(
+            !with_trace
+                .with_details(None, false)
+                .server
+                .unwrap()
+                .display_stacktrace
+        );
+        assert!(
+            !status(&[])
+                .with_details(None, true)
+                .server
+                .unwrap()
+                .display_stacktrace
+        );
+        // A root error index out of range is no details.
+        let out_of_range = spark_connect_proto::FetchErrorDetailsResponse {
+            root_error_idx: Some(3),
+            ..Default::default()
+        };
+        let err = status(&[]).with_details(Some(out_of_range), true);
+        assert_eq!(err.message(), "[X] message");
+        assert_eq!(err.get_stacktrace(), None);
+    }
+
+    #[test]
+    fn a_cause_cycle_ends_the_stack_trace() {
+        use spark_connect_proto::fetch_error_details_response::Error;
+        let error = |cause| Error {
+            error_type_hierarchy: vec!["java.lang.Exception".to_string()],
+            message: "loop".to_string(),
+            cause_idx: Some(cause),
+            ..Default::default()
+        };
+        assert_eq!(
+            jvm_stacktrace(0, &[error(1), error(0)]),
+            "java.lang.Exception\nCaused by: java.lang.Exception: loop"
+        );
+    }
+
+    #[test]
+    fn a_status_without_an_error_info_is_not_a_server_error() {
+        let err = SparkError::from_grpc_status(Status::unavailable("connection 
refused"));
+        assert!(err.server.is_none());
+        assert_eq!(err.kind, SparkErrorKind::Connect);
+        assert_eq!(err.grpc_code(), Some(tonic::Code::Unavailable as i32));
+        let message = err.message();
+        assert!(message.ends_with("connection refused"), "{message}");
+        // Details are only for a server error.
+        let unchanged = err.with_details(None, true);
+        assert!(unchanged.server.is_none());
+        assert_eq!(unchanged.message(), message);
     }
 
     #[test]
diff --git a/crates/spark-connect/src/catalog.rs 
b/crates/spark-connect/src/catalog.rs
index ec705fc..f6a3201 100644
--- a/crates/spark-connect/src/catalog.rs
+++ b/crates/spark-connect/src/catalog.rs
@@ -1034,7 +1034,13 @@ impl Catalog {
         let mut rows = vec![];
 
         loop {
-            let resp = 
block_on(stream.message()).map_err(SparkError::from_grpc_status)?;
+            let client = self.session.client();
+            let resp = block_on(async {
+                match stream.message().await {
+                    Ok(resp) => Ok(resp),
+                    Err(status) => Err(client.error_from_status(status).await),
+                }
+            })?;
             let Some(resp) = resp else {
                 break;
             };
diff --git a/crates/spark-connect/src/lib.rs b/crates/spark-connect/src/lib.rs
index 2b2c870..e12c0a4 100644
--- a/crates/spark-connect/src/lib.rs
+++ b/crates/spark-connect/src/lib.rs
@@ -58,7 +58,10 @@ pub use resource::{
 pub use session::{SparkSession, SparkSessionBuilder};
 /// Re-exported so fallible APIs (e.g. the `#[spark_wasm_udf]`-generated UDF
 /// constructors) can name the client's `Result`/error types.
-pub use spark_connect_core::error::{Result, SparkError};
+pub use spark_connect_core::error::{
+    BreakingChangeInfo, QueryContext, QueryContextType, Result, 
ServerErrorInfo, SparkError,
+    SparkErrorKind,
+};
 /// Re-exported so `persist(...)` / `storage_level()` have a public 
storage-level type.
 pub use spark_connect_proto::StorageLevel;
 /// Named `StorageLevel` presets (`MEMORY_AND_DISK`, `DISK_ONLY`, ...) 
mirroring `pyspark.StorageLevel`.
diff --git a/crates/spark-connect/src/streaming.rs 
b/crates/spark-connect/src/streaming.rs
index 841d885..600ae28 100644
--- a/crates/spark-connect/src/streaming.rs
+++ b/crates/spark-connect/src/streaming.rs
@@ -459,9 +459,13 @@ impl DataStreamWriter {
         let mut query_id = String::new();
         let mut run_id = String::new();
         let mut name = self.query_name.clone();
-        while let Some(resp) =
-            
block_on(response_stream.message()).map_err(SparkError::from_grpc_status)?
-        {
+        let client = self.session.client();
+        while let Some(resp) = block_on(async {
+            match response_stream.message().await {
+                Ok(resp) => Ok(resp),
+                Err(status) => Err(client.error_from_status(status).await),
+            }
+        })? {
             if let Some(
                 
proto::execute_plan_response::ResponseType::WriteStreamOperationStartResult(res),
             ) = resp.response_type
diff --git a/crates/spark-connect/tests/e2e_session_catalog.rs 
b/crates/spark-connect/tests/e2e_session_catalog.rs
index 036825d..1f52f20 100644
--- a/crates/spark-connect/tests/e2e_session_catalog.rs
+++ b/crates/spark-connect/tests/e2e_session_catalog.rs
@@ -186,3 +186,42 @@ fn session_progress_handlers() {
     spark.remove_progress_handler(id);
     spark.clear_progress_handlers();
 }
+
+/// A server error carries its kind, condition, parameters, SQL state, stack 
trace and query
+/// contexts, as the reference client reads them.
+#[test]
+fn server_errors_carry_their_condition_and_details() {
+    use spark_connect::SparkErrorKind;
+    if !should_run() {
+        return;
+    }
+    let spark = session();
+    // Raised at `sql()`, or at the action where `sql()` does not run the 
statement.
+    let err = match spark.sql("SELEC 1") {
+        Ok(df) => df.collect().expect_err("a syntax error"),
+        Err(err) => err,
+    };
+    assert_eq!(err.kind, SparkErrorKind::Parse);
+    assert_eq!(err.get_condition().as_deref(), Some("PARSE_SYNTAX_ERROR"));
+    assert_eq!(err.get_sql_state().as_deref(), Some("42601"));
+    assert_eq!(err.params.get("error").map(String::as_str), Some("'SELEC'"));
+    // The server's message, which names the condition once.
+    assert_eq!(err.to_string().matches("[PARSE_SYNTAX_ERROR]").count(), 1);
+    assert!(err
+        .get_stacktrace()
+        .unwrap()
+        .starts_with("org.apache.spark.sql.catalyst.parser.ParseException"));
+    // spark.sql.connect.serverStacktrace.enabled is true by default.
+    assert!(err.server.as_ref().unwrap().display_stacktrace);
+
+    let err = spark
+        .sql("SELECT 1/0")
+        .expect("a query")
+        .collect()
+        .expect_err("a division by zero");
+    assert_eq!(err.kind, SparkErrorKind::Arithmetic);
+    assert_eq!(err.get_condition().as_deref(), Some("DIVIDE_BY_ZERO"));
+    let contexts = err.get_query_context();
+    assert_eq!(contexts.len(), 1);
+    assert_eq!(contexts[0].fragment(), "1/0");
+}
diff --git a/python/pyspark/errors/exceptions/__init__.py 
b/python/pyspark/errors/exceptions/__init__.py
index 85add6c..4bcc253 100644
--- a/python/pyspark/errors/exceptions/__init__.py
+++ b/python/pyspark/errors/exceptions/__init__.py
@@ -39,10 +39,11 @@ def _operation_id(self):  # type: ignore[no-untyped-def]
     return getattr(self, "_operation_id", None)
 
 
-# pyspark 4.3.0 adds ``SparkConnectException.operation_id``. In this drop-in 
the Connect
-# exception classes ARE the canonical base classes 
(``connect.SparkConnectException`` aliases
-# ``PySparkException``), so the property lives on that shared base; the Rust 
transport sets
-# ``_operation_id`` on errors raised for an ExecutePlan. ``base.py`` is 
vendored, hence here.
+# pyspark 4.3.0 adds ``SparkConnectException.operation_id``. The Rust 
transport sets
+# ``_operation_id`` on the errors that it raises for an ExecutePlan: an error 
that the server
+# raised is one of the Connect classes, which have the property, but another 
error, such as a
+# failed RPC, is one of the base classes, so the property is on their shared 
base as well.
+# ``base.py`` is vendored, hence here.
 if not hasattr(PySparkException, "operation_id"):
     PySparkException.operation_id = property(_operation_id)  # type: 
ignore[attr-defined]
 
diff --git a/python/pyspark/errors/exceptions/connect.py 
b/python/pyspark/errors/exceptions/connect.py
index 14a1768..93e8d9a 100644
--- a/python/pyspark/errors/exceptions/connect.py
+++ b/python/pyspark/errors/exceptions/connect.py
@@ -14,61 +14,338 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
-"""Connect-flavored exceptions.
-
-In upstream pyspark this module parses gRPC ``FetchErrorDetails`` into typed
-exceptions. In this Rust-backed drop-in the transport already performs that
-parsing in Rust and raises the canonical ``pyspark.errors`` classes, so the
-Connect exception types are the same classes re-exported under this import path
-(what upstream code and tests import as 
``pyspark.errors.exceptions.connect.*``).
+"""Exceptions raised from Spark Connect.
+
+The classes are those of upstream pyspark. Upstream, ``convert_exception`` 
converts the gRPC
+``ErrorInfo`` and ``FetchErrorDetails`` of an error that the server raised 
into one of them.
+In this Rust-backed drop-in, the Rust transport fetches and reads those, and
+``_convert_server_error`` picks and builds the exception from what it read, as 
the rest of
+upstream ``_convert_exception`` does. ``grpc`` is optional: without it, 
``StatusCode`` is an
+enum with the members and values of ``grpc.StatusCode``.
 """
-from typing import Any
+import enum
+from types import SimpleNamespace
+from typing import Any, Dict, List, Optional
+
+try:
+    from grpc import StatusCode
+except ImportError:  # pragma: no cover - grpcio is not a dependency of this 
client
+
+    class StatusCode(enum.Enum):  # type: ignore[no-redef]
+        """The status codes of gRPC, as ``grpc.StatusCode`` has them."""
+
+        OK = (0, "ok")
+        CANCELLED = (1, "cancelled")
+        UNKNOWN = (2, "unknown")
+        INVALID_ARGUMENT = (3, "invalid argument")
+        DEADLINE_EXCEEDED = (4, "deadline exceeded")
+        NOT_FOUND = (5, "not found")
+        ALREADY_EXISTS = (6, "already exists")
+        PERMISSION_DENIED = (7, "permission denied")
+        RESOURCE_EXHAUSTED = (8, "resource exhausted")
+        FAILED_PRECONDITION = (9, "failed precondition")
+        ABORTED = (10, "aborted")
+        OUT_OF_RANGE = (11, "out of range")
+        UNIMPLEMENTED = (12, "unimplemented")
+        INTERNAL = (13, "internal")
+        UNAVAILABLE = (14, "unavailable")
+        DATA_LOSS = (15, "data loss")
+        UNAUTHENTICATED = (16, "unauthenticated")
+
 
 from pyspark.errors.exceptions.base import (
-    AnalysisException,
-    ArithmeticException,
-    ArrayIndexOutOfBoundsException,
-    DateTimeException,
-    IllegalArgumentException,
-    NumberFormatException,
-    ParseException,
+    AnalysisException as BaseAnalysisException,
+    IllegalArgumentException as BaseIllegalArgumentException,
+    ArithmeticException as BaseArithmeticException,
+    UnsupportedOperationException as BaseUnsupportedOperationException,
+    ArrayIndexOutOfBoundsException as BaseArrayIndexOutOfBoundsException,
+    DateTimeException as BaseDateTimeException,
+    NumberFormatException as BaseNumberFormatException,
+    ParseException as BaseParseException,
     PySparkException,
-    PythonException,
+    PythonException as BasePythonException,
+    StreamingQueryException as BaseStreamingQueryException,
+    QueryExecutionException as BaseQueryExecutionException,
+    SparkRuntimeException as BaseSparkRuntimeException,
+    SparkNoSuchElementException as BaseNoSuchElementException,
+    SparkUpgradeException as BaseSparkUpgradeException,
     QueryContext as BaseQueryContext,
     QueryContextType,
-    QueryExecutionException,
-    SparkNoSuchElementException,
-    SparkRuntimeException,
-    SparkUpgradeException,
-    StreamingPythonRunnerInitializationException,
-    StreamingQueryException,
-    TempTableAlreadyExistsException,
-    UnsupportedOperationException,
+    StreamingPythonRunnerInitializationException as 
BaseStreamingPythonRunnerInitException,
+    PickleException as BasePickleException,
+    UnknownException as BaseUnknownException,
+    recover_python_exception,
 )
 
-# `SparkConnectException` is the Connect base; here it aliases the canonical 
base class.
-SparkConnectException = PySparkException
-SparkConnectGrpcException = PySparkException
+# Exported here too, as this module did before it had the classes of upstream 
pyspark.
+from pyspark.errors.exceptions.base import TempTableAlreadyExistsException  # 
noqa: F401
+
+
+class SparkConnectException(PySparkException):
+    """
+    Exception thrown from Spark Connect.
+    """
+
+    @property
+    def operation_id(self) -> Optional[str]:
+        """The Spark Connect ExecutePlan operation ID, when available.
+
+        .. versionadded:: 4.3.0
+        """
+        return getattr(self, "_operation_id", None)
+
+
+class SparkConnectGrpcException(SparkConnectException):
+    """
+    Base class to handle the errors from GRPC.
+    """
+
+    def __init__(
+        self,
+        message: Optional[str] = None,
+        errorClass: Optional[str] = None,
+        messageParameters: Optional[Dict[str, str]] = None,
+        reason: Optional[str] = None,
+        sql_state: Optional[str] = None,
+        server_stacktrace: Optional[str] = None,
+        display_server_stacktrace: bool = False,
+        contexts: Optional[List[BaseQueryContext]] = None,
+        grpc_status_code: StatusCode = StatusCode.UNKNOWN,
+        breaking_change_info: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        if contexts is None:
+            contexts = []
+        self._message = message  # type: ignore[assignment]
+        if reason is not None:
+            self._message = f"({reason}) {self._message}"
+
+        # PySparkException has the assumption that errorClass and 
messageParameters are
+        # only occurring together. If only one is set, we assume the message 
to be fully
+        # parsed.
+        tmp_error_class = errorClass
+        tmp_message_parameters = messageParameters
+        if errorClass is not None and messageParameters is None:
+            tmp_error_class = None
+        elif errorClass is None and messageParameters is not None:
+            tmp_message_parameters = None
+
+        super().__init__(
+            message=self._message,
+            errorClass=tmp_error_class,
+            messageParameters=tmp_message_parameters,
+        )
+        self._errorClass = errorClass
+        self._sql_state: Optional[str] = sql_state
+        self._stacktrace: Optional[str] = server_stacktrace
+        self._display_stacktrace: bool = display_server_stacktrace
+        self._contexts: List[BaseQueryContext] = contexts
+        self._grpc_status_code = grpc_status_code
+        self._breaking_change_info: Optional[Dict[str, Any]] = 
breaking_change_info
+        self._log_exception()
+
+    def getSqlState(self) -> Optional[str]:
+        if self._sql_state is not None:
+            return self._sql_state
+        else:
+            return super().getSqlState()
+
+    def getStackTrace(self) -> Optional[str]:
+        return self._stacktrace
+
+    def getMessage(self) -> str:
+        desc = self._message
+        if self._display_stacktrace:
+            desc += "\n\nJVM stacktrace:\n%s" % self._stacktrace
+        return desc
+
+    def getGrpcStatusCode(self) -> StatusCode:
+        return self._grpc_status_code
+
+    def getBreakingChangeInfo(self) -> Optional[Dict[str, Any]]:
+        """
+        Returns the breaking change info for an error, or None.
+
+        For Spark Connect exceptions, this returns the breaking change info
+        received from the server, rather than looking it up from local error 
files.
+        """
+        return self._breaking_change_info
+
+    def __str__(self) -> str:
+        return self.getMessage()
+
+
+class UnknownException(SparkConnectGrpcException, BaseUnknownException):
+    """
+    Exception for unmapped errors in Spark Connect.
+    This class is functionally identical to SparkConnectGrpcException but has 
a different name
+    for consistency.
+    """
+
+    def __init__(
+        self,
+        message: Optional[str] = None,
+        errorClass: Optional[str] = None,
+        messageParameters: Optional[Dict[str, str]] = None,
+        reason: Optional[str] = None,
+        sql_state: Optional[str] = None,
+        server_stacktrace: Optional[str] = None,
+        display_server_stacktrace: bool = False,
+        contexts: Optional[List[BaseQueryContext]] = None,
+        grpc_status_code: StatusCode = StatusCode.UNKNOWN,
+        breaking_change_info: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(
+            message=message,
+            errorClass=errorClass,
+            messageParameters=messageParameters,
+            reason=reason,
+            sql_state=sql_state,
+            server_stacktrace=server_stacktrace,
+            display_server_stacktrace=display_server_stacktrace,
+            contexts=contexts,
+            grpc_status_code=grpc_status_code,
+            breaking_change_info=breaking_change_info,
+        )
+
+
+class AnalysisException(SparkConnectGrpcException, BaseAnalysisException):
+    """
+    Failed to analyze a SQL query plan, thrown from Spark Connect.
+    """
+
+
+class ParseException(AnalysisException, BaseParseException):
+    """
+    Failed to parse a SQL command, thrown from Spark Connect.
+    """
+
+
+class IllegalArgumentException(SparkConnectGrpcException, 
BaseIllegalArgumentException):
+    """
+    Passed an illegal or inappropriate argument, thrown from Spark Connect.
+    """
+
+
+class StreamingQueryException(SparkConnectGrpcException, 
BaseStreamingQueryException):
+    """
+    Exception that stopped a :class:`StreamingQuery` thrown from Spark Connect.
+    """
+
+
+class QueryExecutionException(SparkConnectGrpcException, 
BaseQueryExecutionException):
+    """
+    Failed to execute a query, thrown from Spark Connect.
+    """
+
+
+class PythonException(SparkConnectGrpcException, BasePythonException):
+    """
+    Exceptions thrown from Spark Connect.
+    """
+
+
+class ArithmeticException(SparkConnectGrpcException, BaseArithmeticException):
+    """
+    Arithmetic exception thrown from Spark Connect.
+    """
+
+
+class UnsupportedOperationException(SparkConnectGrpcException, 
BaseUnsupportedOperationException):
+    """
+    Unsupported operation exception thrown from Spark Connect.
+    """
+
+
+class ArrayIndexOutOfBoundsException(SparkConnectGrpcException, 
BaseArrayIndexOutOfBoundsException):
+    """
+    Array index out of bounds exception thrown from Spark Connect.
+    """
+
+
+class DateTimeException(SparkConnectGrpcException, BaseDateTimeException):
+    """
+    Datetime exception thrown from Spark Connect.
+    """
+
+
+class NumberFormatException(IllegalArgumentException, 
BaseNumberFormatException):
+    """
+    Number format exception thrown from Spark Connect.
+    """
+
+
+class SparkRuntimeException(SparkConnectGrpcException, 
BaseSparkRuntimeException):
+    """
+    Runtime exception thrown from Spark Connect.
+    """
+
+
+class SparkUpgradeException(SparkConnectGrpcException, 
BaseSparkUpgradeException):
+    """
+    Exception thrown because of Spark upgrade from Spark Connect.
+    """
 
 
 class SparkException(SparkConnectGrpcException):
     """ """
 
 
-class InvalidPlanInput(SparkConnectGrpcException):
-    """Error thrown when a connect plan is not valid."""
+class SparkNoSuchElementException(SparkConnectGrpcException, 
BaseNoSuchElementException):
+    """
+    No such element exception.
+    """
 
 
-def _unsupported(class_name: str, method_name: str) -> 
"UnsupportedOperationException":
-    return UnsupportedOperationException(
-        errorClass="UNSUPPORTED_CALL.WITHOUT_SUGGESTION",
-        messageParameters={"className": class_name, "methodName": method_name},
-    )
+class InvalidPlanInput(SparkConnectGrpcException):
+    """
+    Error thrown when a connect plan is not valid.
+    """
+
+
+class StreamingPythonRunnerInitializationException(
+    SparkConnectGrpcException, BaseStreamingPythonRunnerInitException
+):
+    """
+    Failed to initialize a streaming Python runner.
+    """
+
+
+class PickleException(SparkConnectGrpcException, BasePickleException):
+    """
+    Represents an exception which is failed while pickling from server side
+    such as `net.razorvine.pickle.PickleException`. This is different from 
`PySparkPicklingError`
+    which represents an exception failed from Python built-in 
`pickle.PicklingError`.
+    """
+
+
+# Update EXCEPTION_CLASS_MAPPING here when adding a new exception
+EXCEPTION_CLASS_MAPPING = {
+    "org.apache.spark.sql.catalyst.parser.ParseException": ParseException,
+    "org.apache.spark.sql.AnalysisException": AnalysisException,
+    "org.apache.spark.sql.streaming.StreamingQueryException": 
StreamingQueryException,
+    "org.apache.spark.sql.execution.QueryExecutionException": 
QueryExecutionException,
+    "java.lang.NumberFormatException": NumberFormatException,
+    "java.lang.IllegalArgumentException": IllegalArgumentException,
+    "java.lang.ArithmeticException": ArithmeticException,
+    "java.lang.UnsupportedOperationException": UnsupportedOperationException,
+    "java.lang.ArrayIndexOutOfBoundsException": ArrayIndexOutOfBoundsException,
+    "java.time.DateTimeException": DateTimeException,
+    "org.apache.spark.SparkRuntimeException": SparkRuntimeException,
+    "org.apache.spark.SparkUpgradeException": SparkUpgradeException,
+    "org.apache.spark.api.python.PythonException": PythonException,
+    "org.apache.spark.SparkNoSuchElementException": 
SparkNoSuchElementException,
+    "org.apache.spark.SparkException": SparkException,
+    "org.apache.spark.sql.connect.common.InvalidPlanInput": InvalidPlanInput,
+    "org.apache.spark.api.python.StreamingPythonRunner"
+    "$StreamingPythonRunnerInitializationException": 
StreamingPythonRunnerInitializationException,
+}
+
+THIRD_PARTY_EXCEPTION_CLASS_MAPPING = {
+    "net.razorvine.pickle.PickleException": PickleException,
+}
 
 
 class SQLQueryContext(BaseQueryContext):
-    """A SQL query context parsed from server error details."""
-
     def __init__(self, q: Any):
         self._q = q
 
@@ -91,15 +368,21 @@ class SQLQueryContext(BaseQueryContext):
         return str(self._q.fragment)
 
     def callSite(self) -> str:
-        raise _unsupported("SQLQueryContext", "callSite")
+        raise UnsupportedOperationException(
+            "",
+            errorClass="UNSUPPORTED_CALL.WITHOUT_SUGGESTION",
+            messageParameters={"className": "SQLQueryContext", "methodName": 
"callSite"},
+            sql_state="0A000",
+            server_stacktrace=None,
+            display_server_stacktrace=False,
+            contexts=[],
+        )
 
     def summary(self) -> str:
         return str(self._q.summary)
 
 
 class DataFrameQueryContext(BaseQueryContext):
-    """A DataFrame query context parsed from server error details."""
-
     def __init__(self, q: Any):
         self._q = q
 
@@ -107,16 +390,48 @@ class DataFrameQueryContext(BaseQueryContext):
         return QueryContextType.DataFrame
 
     def objectType(self) -> str:
-        raise _unsupported("DataFrameQueryContext", "objectType")
+        raise UnsupportedOperationException(
+            "",
+            errorClass="UNSUPPORTED_CALL.WITHOUT_SUGGESTION",
+            messageParameters={"className": "DataFrameQueryContext", 
"methodName": "objectType"},
+            sql_state="0A000",
+            server_stacktrace=None,
+            display_server_stacktrace=False,
+            contexts=[],
+        )
 
     def objectName(self) -> str:
-        raise _unsupported("DataFrameQueryContext", "objectName")
+        raise UnsupportedOperationException(
+            "",
+            errorClass="UNSUPPORTED_CALL.WITHOUT_SUGGESTION",
+            messageParameters={"className": "DataFrameQueryContext", 
"methodName": "objectName"},
+            sql_state="0A000",
+            server_stacktrace=None,
+            display_server_stacktrace=False,
+            contexts=[],
+        )
 
     def startIndex(self) -> int:
-        raise _unsupported("DataFrameQueryContext", "startIndex")
+        raise UnsupportedOperationException(
+            "",
+            errorClass="UNSUPPORTED_CALL.WITHOUT_SUGGESTION",
+            messageParameters={"className": "DataFrameQueryContext", 
"methodName": "startIndex"},
+            sql_state="0A000",
+            server_stacktrace=None,
+            display_server_stacktrace=False,
+            contexts=[],
+        )
 
     def stopIndex(self) -> int:
-        raise _unsupported("DataFrameQueryContext", "stopIndex")
+        raise UnsupportedOperationException(
+            "",
+            errorClass="UNSUPPORTED_CALL.WITHOUT_SUGGESTION",
+            messageParameters={"className": "DataFrameQueryContext", 
"methodName": "stopIndex"},
+            sql_state="0A000",
+            server_stacktrace=None,
+            display_server_stacktrace=False,
+            contexts=[],
+        )
 
     def fragment(self) -> str:
         return str(self._q.fragment)
@@ -128,28 +443,83 @@ class DataFrameQueryContext(BaseQueryContext):
         return str(self._q.summary)
 
 
-__all__ = [
-    "SparkConnectException",
-    "SparkConnectGrpcException",
-    "SparkException",
-    "InvalidPlanInput",
-    "SQLQueryContext",
-    "DataFrameQueryContext",
-    "AnalysisException",
-    "ArithmeticException",
-    "ArrayIndexOutOfBoundsException",
-    "DateTimeException",
-    "IllegalArgumentException",
-    "NumberFormatException",
-    "ParseException",
-    "PySparkException",
-    "PythonException",
-    "QueryExecutionException",
-    "SparkNoSuchElementException",
-    "SparkRuntimeException",
-    "SparkUpgradeException",
-    "StreamingPythonRunnerInitializationException",
-    "StreamingQueryException",
-    "TempTableAlreadyExistsException",
-    "UnsupportedOperationException",
-]
+def _status_code(code: int) -> StatusCode:
+    """The ``StatusCode`` of a gRPC status code number, or ``UNKNOWN`` for 
another number."""
+    for status_code in StatusCode:
+        if status_code.value[0] == code:
+            return status_code
+    return StatusCode.UNKNOWN
+
+
+def _convert_server_error(
+    classes: List[str],
+    sql_state: Optional[str],
+    error_class: Optional[str],
+    reason: Optional[str],
+    message: str,
+    message_parameters: Optional[Dict[str, str]],
+    stacktrace: Optional[str],
+    display_server_stacktrace: bool,
+    contexts: Optional[List[Dict[str, Any]]],
+    grpc_status_code: int,
+    breaking_change_info: Optional[Dict[str, Any]],
+) -> SparkConnectException:
+    """The exception for an error that the server raised, from what the Rust 
transport read of
+    its ``ErrorInfo`` and ``FetchErrorDetails``. Picks and builds it as 
upstream
+    ``_convert_exception`` does once it has read them."""
+    grpc_status_code = _status_code(grpc_status_code)  # type: 
ignore[assignment]
+    if contexts is not None:
+        contexts = [  # type: ignore[misc]
+            (SQLQueryContext if c["context_type"] == "SQL" else 
DataFrameQueryContext)(
+                SimpleNamespace(**c)
+            )
+            for c in contexts
+        ]
+
+    if "org.apache.spark.api.python.PythonException" in classes:
+        converted: SparkConnectException = PythonException(
+            message="\n  An exception was thrown from the Python worker. "
+            "Please see the stack trace below.\n%s" % message,
+            grpc_status_code=grpc_status_code,
+        )
+        return recover_python_exception(converted)
+
+    # Return exception based on class mapping
+    for error_class_name in classes:
+        ExceptionClass = EXCEPTION_CLASS_MAPPING.get(error_class_name)
+        if ExceptionClass is SparkException:
+            for third_party_exception_class in 
THIRD_PARTY_EXCEPTION_CLASS_MAPPING:
+                ExceptionClass = (
+                    
THIRD_PARTY_EXCEPTION_CLASS_MAPPING.get(third_party_exception_class)
+                    if third_party_exception_class in message
+                    else SparkException
+                )
+
+        if ExceptionClass:
+            converted = ExceptionClass(
+                message,
+                errorClass=error_class,
+                messageParameters=message_parameters,
+                sql_state=sql_state,
+                server_stacktrace=stacktrace,
+                display_server_stacktrace=display_server_stacktrace,
+                contexts=contexts,  # type: ignore[arg-type]
+                grpc_status_code=grpc_status_code,
+                breaking_change_info=breaking_change_info,
+            )
+            return recover_python_exception(converted)
+
+    # Return UnknownException if there is no matched exception class
+    converted = UnknownException(
+        message,
+        reason=reason,
+        messageParameters=message_parameters,
+        errorClass=error_class,
+        sql_state=sql_state,
+        server_stacktrace=stacktrace,
+        display_server_stacktrace=display_server_stacktrace,
+        contexts=contexts,  # type: ignore[arg-type]
+        grpc_status_code=grpc_status_code,
+        breaking_change_info=breaking_change_info,
+    )
+    return recover_python_exception(converted)
diff --git a/python/tests/_mock_connect_server.py 
b/python/tests/_mock_connect_server.py
index 72a6bed..5e88ee3 100644
--- a/python/tests/_mock_connect_server.py
+++ b/python/tests/_mock_connect_server.py
@@ -126,11 +126,40 @@ def serve(connection):
         execute_requests = []
         execute_payload = b""
         execute_failure = None
+        # With `execute_error` set to (message, reason, metadata), ExecutePlan 
fails as the
+        # server does for an error that it raised: INTERNAL, with a 
google.rpc.Status of an
+        # ErrorInfo of `reason` and `metadata` in grpc-status-details-bin.
+        execute_error = None
+        # FetchErrorDetails returns `error_details` (raw 
FetchErrorDetailsResponse fields) and
+        # records the error id asked for. Config Get returns the values in 
`confs`, and fails
+        # for a key without one, as the server does for an unset config; it 
records the keys.
+        error_details = b""
+        fetched_error_ids = []
+        confs = {}
+        read_confs = []
 
         def execute(self, request, context):
             self.execute_requests.append(request)
             if self.execute_failure:
                 context.abort(grpc.StatusCode.INVALID_ARGUMENT, 
self.execute_failure)
+            if self.execute_error:
+                message, reason, metadata = self.execute_error
+                # google.rpc: Status.code=1, message=2, details=3; 
Any.type_url=1, value=2;
+                # ErrorInfo.reason=1, domain=2, metadata=3 (entries of key=1, 
value=2).
+                info = message_field(1, reason) + message_field(2, 
"org.apache.spark")
+                for key, value in metadata.items():
+                    info += message_field(3, message_field(1, key) + 
message_field(2, value))
+                status = (
+                    varint_field(1, grpc.StatusCode.INTERNAL.value[0])
+                    + message_field(2, message)
+                    + message_field(
+                        3,
+                        message_field(1, 
"type.googleapis.com/google.rpc.ErrorInfo")
+                        + message_field(2, info),
+                    )
+                )
+                context.set_trailing_metadata((("grpc-status-details-bin", 
status),))
+                context.abort(grpc.StatusCode.INTERNAL, message)
             # ExecutePlanRequest.operation_id=6; 
ExecutePlanResponse.operation_id=12,
             # response_id=13, result_complete=14.
             operation_id = parse_message(request).get(6, [b""])[0]
@@ -138,6 +167,28 @@ def serve(connection):
             yield header + message_field(13, "r1") + self.execute_payload
             yield header + message_field(13, "r2") + message_field(14, b"")
 
+        def fetch_error_details(self, request, context):
+            # FetchErrorDetailsRequest.error_id=3.
+            
self.fetched_error_ids.append(parse_message(request)[3][0].decode())
+            return self.error_details
+
+        def config(self, request, context):
+            # ConfigRequest.session_id=1, operation=3, Operation.get=2, 
Get.keys=1;
+            # ConfigResponse.session_id=1, pairs=2, KeyValue.key=1, value=2.
+            request = parse_message(request)
+            operation = parse_message(request[3][0])
+            if 2 not in operation:
+                context.abort(grpc.StatusCode.UNIMPLEMENTED, "only Get is 
served")
+            keys = [key.decode() for key in 
parse_message(operation[2][0]).get(1, [])]
+            self.read_confs.extend(keys)
+            if any(key not in self.confs for key in keys):
+                context.abort(grpc.StatusCode.INTERNAL, "[SQL_CONF_NOT_FOUND]")
+            # The response names the session, as the server's does.
+            return message_field(1, request[1][0]) + b"".join(
+                message_field(2, message_field(1, key) + message_field(2, 
self.confs[key]))
+                for key in keys
+            )
+
     service = Service()
     with ThreadPoolExecutor(max_workers=4) as executor:
         server = grpc.server(executor)
@@ -149,6 +200,8 @@ def serve(connection):
                 lambda request, context: iter([message_field(14, b"")])
             ),
             "ReleaseExecute": grpc.unary_unary_rpc_method_handler(lambda 
request, context: b""),
+            "FetchErrorDetails": 
grpc.unary_unary_rpc_method_handler(service.fetch_error_details),
+            "Config": grpc.unary_unary_rpc_method_handler(service.config),
         }
         server.add_generic_rpc_handlers(
             
(grpc.method_handlers_generic_handler("spark.connect.SparkConnectService", 
handlers),)
diff --git a/python/tests/test_dropin_e2e.py b/python/tests/test_dropin_e2e.py
index c0b59b8..060552a 100644
--- a/python/tests/test_dropin_e2e.py
+++ b/python/tests/test_dropin_e2e.py
@@ -263,3 +263,37 @@ def 
test_collect_reads_a_result_across_stream_ends(session):
     n = 300_000
     assert len(session.range(n).collect()) == n
     assert session.range(n).toArrow().num_rows == n
+
+
+def test_server_errors_carry_their_condition_and_details(session):
+    from pyspark.errors import AnalysisException, ArithmeticException, 
ParseException
+    from pyspark.errors.exceptions.connect import SparkConnectGrpcException, 
SQLQueryContext
+
+    with pytest.raises(ParseException) as error:
+        session.sql("SELEC 1").collect()
+    e = error.value
+    assert isinstance(e, SparkConnectGrpcException)
+    assert e.getCondition() == "PARSE_SYNTAX_ERROR"
+    assert e.getSqlState() == "42601"
+    assert e.getMessageParameters() == {"error": "'SELEC'", "hint": ""}
+    # The server's message, which names the condition once.
+    assert str(e).count("[PARSE_SYNTAX_ERROR]") == 1
+    assert 
e.getStackTrace().startswith("org.apache.spark.sql.catalyst.parser.ParseException")
+
+    with pytest.raises(AnalysisException) as error:
+        session.table("no_such_table_xyz").collect()
+    e = error.value
+    assert e.getCondition() == "TABLE_OR_VIEW_NOT_FOUND"
+    assert e.getSqlState() == "42P01"
+    assert list(e.getMessageParameters()) == ["relationName", "searchPath"]
+    assert e.getMessageParameters()["relationName"] == "`no_such_table_xyz`"
+
+    with pytest.raises(ArithmeticException) as error:
+        session.sql("SELECT 1/0").collect()
+    e = error.value
+    assert e.getCondition() == "DIVIDE_BY_ZERO"
+    [context] = e.getQueryContext()
+    assert isinstance(context, SQLQueryContext)
+    assert context.fragment() == "1/0"
+    # spark.sql.connect.serverStacktrace.enabled is true by default.
+    assert "\n\nJVM stacktrace:\norg.apache.spark.SparkArithmeticException" in 
str(e)
diff --git a/python/tests/test_dropin_offline.py 
b/python/tests/test_dropin_offline.py
index 41a2ad0..413fcef 100644
--- a/python/tests/test_dropin_offline.py
+++ b/python/tests/test_dropin_offline.py
@@ -6,6 +6,7 @@ Python side has real, measurable coverage in CI without a 
running server. Tests
 that require a live server live in test_dropin_e2e.py and are gated on 
SPARK_REMOTE.
 """
 
+import json
 import pickle
 import time
 from collections import namedtuple
@@ -3891,7 +3892,10 @@ def test_sql_context_connect_backed():
 
 def test_execution_info_and_operation_id():
     from pyspark.errors import AnalysisException
-    from pyspark.errors.exceptions.connect import SparkConnectException
+    from pyspark.errors.exceptions.connect import (
+        AnalysisException as ConnectAnalysisException,
+        SparkConnectException,
+    )
     from pyspark.sql.connect.client import PlanObservedMetrics
     from pyspark.sql.metrics import ExecutionInfo
 
@@ -3906,8 +3910,10 @@ def test_execution_info_and_operation_id():
     assert ei.flows == [("o", {"observed_metric_0": 1, "observed_metric_1": 
2})]
     assert ei.metrics is None
     # SparkConnectException.operation_id (4.3.0): None unless the transport 
stamped it.
-    err = AnalysisException("boom")
+    err = ConnectAnalysisException("boom")
     assert isinstance(err, SparkConnectException)
+    assert isinstance(err, AnalysisException)
+    assert not isinstance(AnalysisException("boom"), SparkConnectException)
     assert err.operation_id is None
     err._operation_id = "op-2"
     assert err.operation_id == "op-2"
@@ -4021,6 +4027,217 @@ def 
test_execute_plan_error_carries_operation_id(mock_connect):
     assert error.value.operation_id == 
_request_operation_id(service.execute_requests[-1])
 
 
+def _error_info(classes, **metadata):
+    """ErrorInfo metadata as the server sends it, with the exception classes, 
the most
+    specific first."""
+    return {"classes": json.dumps(classes), **metadata}
+
+
+def _stack_element(method, line):
+    # StackTraceElement.declaring_class=1, method_name=2, file_name=3, 
line_number=4.
+    return (
+        message_field(1, "org.apache.spark.Expr")
+        + message_field(2, method)
+        + message_field(3, "Expr.scala")
+        + varint_field(4, line)
+    )
+
+
+def _error_details(message, hierarchy, stack, throwable):
+    # FetchErrorDetailsResponse.root_error_idx=1, errors=2; 
Error.error_type_hierarchy=1,
+    # message=2, stack_trace=3, spark_throwable=5.
+    error = b"".join(message_field(1, name) for name in hierarchy) + 
message_field(2, message)
+    error += b"".join(message_field(3, element) for element in stack)
+    return varint_field(1, 0) + message_field(2, error + message_field(5, 
throwable))
+
+
+ARITHMETIC = ["org.apache.spark.SparkArithmeticException", 
"java.lang.ArithmeticException"]
+
+
+def test_a_server_error_is_raised_with_its_details(mock_connect):
+    import pyspark.errors as E
+    from pyspark.errors.exceptions import connect as C
+
+    spark, service = mock_connect
+    message = "[DIVIDE_BY_ZERO] Division by zero. SQLSTATE: 22012"
+    params = {"config": "spark.sql.ansi.enabled", "alternative": "try_divide"}
+    service.execute_error = (
+        # The status carries a message cut short; the details have all of it.
+        message[:24],
+        ARITHMETIC[0],
+        _error_info(
+            ARITHMETIC,
+            errorClass="DIVIDE_BY_ZERO",
+            sqlState="22012",
+            messageParameters=json.dumps(params),
+            errorId="error-1",
+        ),
+    )
+    # SparkThrowable.error_class=1, message_parameters=2 (entries of key=1, 
value=2),
+    # query_contexts=3, breaking_change_info=5; QueryContext.context_type=10, 
start_index=3,
+    # stop_index=4, fragment=5; BreakingChangeInfo.migration_message=1, 
mitigation_config=2
+    # (key=1, value=2).
+    throwable = message_field(1, "DIVIDE_BY_ZERO")
+    for key, value in params.items():
+        throwable += message_field(2, message_field(1, key) + message_field(2, 
value))
+    throwable += message_field(
+        3, varint_field(10, 0) + varint_field(3, 7) + varint_field(4, 9) + 
message_field(5, "1/0")
+    )
+    throwable += message_field(
+        5,
+        message_field(1, "Set the config.")
+        + message_field(2, message_field(1, "spark.sql.ansi.enabled") + 
message_field(2, "false")),
+    )
+    service.error_details = _error_details(
+        message, ARITHMETIC, [_stack_element("eval", 12)], throwable
+    )
+    service.confs = {"spark.sql.connect.serverStacktrace.enabled": "true"}
+    with pytest.raises(C.ArithmeticException) as error:
+        spark.range(1).collect()
+    e = error.value
+    # Both the Connect exception and the base one, as in the reference client.
+    assert isinstance(e, C.SparkConnectGrpcException)
+    assert isinstance(e, E.ArithmeticException)
+    assert service.fetched_error_ids == ["error-1"]
+    assert e.getCondition() == "DIVIDE_BY_ZERO"
+    assert e.getSqlState() == "22012"
+    # In the order that the server gave them.
+    assert list(e.getMessageParameters().items()) == list(params.items())
+    stacktrace = "\n".join(
+        [ARITHMETIC[0], "\tat org.apache.spark.Expr.eval(Expr.scala:12)"]
+    )
+    assert e.getStackTrace() == stacktrace
+    assert str(e) == message + "\n\nJVM stacktrace:\n" + stacktrace
+    [context] = e.getQueryContext()
+    assert type(context) is C.SQLQueryContext
+    assert (context.fragment(), context.startIndex(), context.stopIndex()) == 
("1/0", 7, 9)
+    assert e.getBreakingChangeInfo() == {
+        "migration_message": ["Set the config."],
+        "needs_audit": True,
+        "mitigation_config": {"key": "spark.sql.ansi.enabled", "value": 
"false"},
+    }
+    assert e.getGrpcStatusCode() == C.StatusCode.INTERNAL
+    assert e.operation_id == 
_request_operation_id(service.execute_requests[-1])
+
+
+PARSE = [
+    "org.apache.spark.sql.catalyst.parser.ParseException",
+    "org.apache.spark.sql.AnalysisException",
+]
+PARSE_MESSAGE = "\n[PARSE_SYNTAX_ERROR] Syntax error at or near 'SELEC'. 
SQLSTATE: 42601"
+
+
[email protected](
+    "confs, shown",
+    [
+        ({"spark.sql.connect.serverStacktrace.enabled": "true"}, True),
+        (
+            {
+                "spark.sql.connect.serverStacktrace.enabled": "false",
+                "spark.sql.pyspark.jvmStacktrace.enabled": "true",
+            },
+            True,
+        ),
+        (
+            {
+                "spark.sql.connect.serverStacktrace.enabled": "false",
+                "spark.sql.pyspark.jvmStacktrace.enabled": "false",
+            },
+            False,
+        ),
+        # A config that cannot be read shows it, as in the reference client.
+        ({}, True),
+        ({"spark.sql.connect.serverStacktrace.enabled": "false"}, True),
+    ],
+)
+def 
test_a_server_error_without_details_keeps_what_its_status_has(mock_connect, 
confs, shown):
+    from pyspark.errors.exceptions import connect as C
+
+    spark, service = mock_connect
+    stacktrace = PARSE[0] + "\n\tat 
org.apache.spark.sql.catalyst.parser.ParseErrorListener"
+    service.execute_error = (
+        PARSE_MESSAGE,
+        PARSE[0],
+        _error_info(
+            PARSE,
+            errorClass="PARSE_SYNTAX_ERROR",
+            sqlState="42601",
+            messageParameters=json.dumps({"error": "'SELEC'", "hint": ""}),
+            stackTrace=stacktrace,
+        ),
+    )
+    service.confs = confs
+    # The most specific class decides: a ParseException is also an 
AnalysisException.
+    with pytest.raises(C.ParseException) as error:
+        spark.range(1).collect()
+    e = error.value
+    assert isinstance(e, C.AnalysisException)
+    # Without an error id, there are no details to fetch.
+    assert service.fetched_error_ids == []
+    assert e.getCondition() == "PARSE_SYNTAX_ERROR"
+    assert e.getMessageParameters() == {"error": "'SELEC'", "hint": ""}
+    assert e.getStackTrace() == stacktrace
+    assert e.getQueryContext() == []
+    assert str(e) == (PARSE_MESSAGE + "\n\nJVM stacktrace:\n" + stacktrace if 
shown else PARSE_MESSAGE)
+
+
[email protected](
+    "classes, message, expected, text",
+    [
+        (
+            ["java.lang.IllegalStateException"],
+            "boom",
+            "UnknownException",
+            "(java.lang.IllegalStateException) boom",
+        ),
+        (
+            ["org.apache.spark.SparkException", 
"org.apache.spark.api.python.PythonException"],
+            "boom",
+            "PythonException",
+            "\n  An exception was thrown from the Python worker. "
+            "Please see the stack trace below.\nboom",
+        ),
+        (
+            ["org.apache.spark.SparkException"],
+            "net.razorvine.pickle.PickleException: expected zero arguments",
+            "PickleException",
+            "net.razorvine.pickle.PickleException: expected zero arguments",
+        ),
+        (["org.apache.spark.SparkException"], "boom", "SparkException", 
"boom"),
+        (
+            ["org.apache.spark.sql.connect.common.InvalidPlanInput"],
+            "boom",
+            "InvalidPlanInput",
+            "boom",
+        ),
+    ],
+)
+def test_the_classes_of_a_server_error_pick_its_exception(
+    mock_connect, classes, message, expected, text
+):
+    from pyspark.errors.exceptions import connect as C
+
+    spark, service = mock_connect
+    service.execute_error = (message, classes[0], _error_info(classes))
+    service.confs = {
+        "spark.sql.connect.serverStacktrace.enabled": "false",
+        "spark.sql.pyspark.jvmStacktrace.enabled": "false",
+    }
+    with pytest.raises(C.SparkConnectGrpcException) as error:
+        spark.range(1).collect()
+    assert type(error.value).__name__ == expected
+    assert type(error.value) is getattr(C, expected)
+    assert str(error.value) == text
+
+
+def test_grpc_status_codes():
+    from pyspark.errors.exceptions.connect import StatusCode, _status_code
+
+    assert _status_code(13) is StatusCode.INTERNAL
+    assert _status_code(0) is StatusCode.OK
+    assert _status_code(99) is StatusCode.UNKNOWN
+
+
 def _sent_define_flow(request):
     """The DefineFlow in a captured ExecutePlanRequest: plan=3 -> command=2 ->
     pipeline_command=19 -> define_flow=3."""


---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]

Reply via email to