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

zhztheplayer pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/gluten.git


The following commit(s) were added to refs/heads/main by this push:
     new 3dae1409f9 [CORE] Preserve Java throwables at the JNI boundary (#13560)
3dae1409f9 is described below

commit 3dae1409f9c8656dbb79d26f31ad5b4b8e0f3dbc
Author: Felipe Pessoto <[email protected]>
AuthorDate: Fri Nov 13 08:46:32 2026 -0800

    [CORE] Preserve Java throwables at the JNI boundary (#13560)
---
 .github/workflows/velox_backend_x86.yml            |  16 +-
 cpp/core/CMakeLists.txt                            |  11 +
 cpp/core/jni/JavaException.cc                      | 198 +++++++++++++
 cpp/core/jni/JavaException.h                       |  62 +++++
 cpp/core/jni/JniCommon.h                           |  28 +-
 cpp/core/jni/JniError.h                            |  30 +-
 cpp/core/tests/CMakeLists.txt                      |   3 +
 cpp/core/tests/JavaExceptionAllocationTest.cc      | 160 +++++++++++
 cpp/core/tests/JavaExceptionJniTest.cc             | 240 ++++++++++++++++
 cpp/core/tests/JavaExceptionTest.cc                | 196 +++++++++++++
 cpp/core/tests/utils/TestJniEnvironment.h          | 179 ++++++++++++
 docs/developers/NewToGluten.md                     |  49 ++++
 gluten-arrow/pom.xml                               |  43 +++
 .../apache/gluten/jni/JavaExceptionJniTest.java    | 310 +++++++++++++++++++++
 14 files changed, 1489 insertions(+), 36 deletions(-)

diff --git a/.github/workflows/velox_backend_x86.yml 
b/.github/workflows/velox_backend_x86.yml
index c7a9ecc288..d73eeb3078 100644
--- a/.github/workflows/velox_backend_x86.yml
+++ b/.github/workflows/velox_backend_x86.yml
@@ -133,6 +133,7 @@ jobs:
   # Output flags:
   #   cpp      – C++ sources, Velox build scripts, or dev tooling changed
   #   java     – any cross-version Java/Scala/Maven source changed
+  #   jni_test – core JNI Java tests, their classes, or build wiring changed
   #   shims34/35/40/41 – version-specific shim layer changed
   #   tools_it – tools/gluten-it changed
   #
@@ -159,6 +160,7 @@ jobs:
       cpp:      ${{ steps.filter.outputs.cpp }}
       java:     ${{ steps.filter.outputs.java }}
       udf:      ${{ steps.filter.outputs.udf }}
+      jni_test: ${{ steps.filter.outputs.jni_test }}
       shims34:  ${{ steps.filter.outputs.shims34 }}
       shims35:  ${{ steps.filter.outputs.shims35 }}
       shims40:  ${{ steps.filter.outputs.shims40 }}
@@ -188,7 +190,7 @@ jobs:
               recent=$(git log --oneline --after="24 hours ago" HEAD | wc -l)
               if [ "$recent" -eq 0 ]; then
                 echo "No commits in the last 24 hours -- skipping nightly run."
-                for flag in cpp java udf shims34 shims35 shims40 shims41 
shims42 tools_it; do
+                for flag in cpp java udf jni_test shims34 shims35 shims40 
shims41 shims42 tools_it; do
                   echo "$flag=false" >> $GITHUB_OUTPUT
                 done
                 echo "full_run=false" >> $GITHUB_OUTPUT
@@ -196,7 +198,7 @@ jobs:
               fi
             fi
             # Run everything, including the extended matrices PR runs skip.
-            for flag in cpp java udf shims34 shims35 shims40 shims41 shims42 
tools_it; do
+            for flag in cpp java udf jni_test shims34 shims35 shims40 shims41 
shims42 tools_it; do
               echo "$flag=true" >> $GITHUB_OUTPUT
             done
             echo "full_run=true" >> $GITHUB_OUTPUT
@@ -224,6 +226,7 @@ jobs:
           echo "cpp=$(match      '^(cpp/|ep/build-velox/|dev/)')"              
                              >> $GITHUB_OUTPUT
           echo "java=$(match     
'^(\.github/(workflows|actions)/|pom\.xml|backends-velox/|gluten-(uniffle|celeborn|ras|core|substrait|arrow|delta|iceberg|hudi|paimon)/|gluten-ut/(common/|test/|src-iceberg-upstream/|pom\.xml)|package/|build/mvn)')"
 >> $GITHUB_OUTPUT
           echo "udf=$(match      
'^(backends-velox/src/test/scala/org/apache/gluten/expression/VeloxUdfSuite\.scala|\.github/workflows/velox_backend_x86\.yml)$')"
 >> $GITHUB_OUTPUT
+          echo "jni_test=$(match 
'^(\.github/workflows/velox_backend_x86\.yml|pom\.xml|gluten-(arrow|core)/pom\.xml|build/mvn|gluten-arrow/src/test/java/org/apache/gluten/jni/.*|gluten-arrow/src/main/java/org/apache/gluten/exception/JniExceptionDescriber\.java|gluten-core/src/main/java/org/apache/gluten/exception/GlutenException\.java)$')"
 >> $GITHUB_OUTPUT
           echo "shims34=$(match  
'^(shims/(spark34|common)/|gluten-ut/spark34/)')"                           >> 
$GITHUB_OUTPUT
           echo "shims35=$(match  
'^(shims/(spark35|common)/|gluten-ut/spark35/)')"                           >> 
$GITHUB_OUTPUT
           echo "shims40=$(match  
'^(shims/(spark40|common)/|gluten-ut/spark40/)')"                           >> 
$GITHUB_OUTPUT
@@ -1160,7 +1163,10 @@ jobs:
 
   cpp-test-udf-test:
     needs: detect-changes
-    if: needs.detect-changes.outputs.cpp == 'true' || 
needs.detect-changes.outputs.udf == 'true'
+    if: >-
+      needs.detect-changes.outputs.cpp == 'true' ||
+      needs.detect-changes.outputs.udf == 'true' ||
+      needs.detect-changes.outputs.jni_test == 'true'
     runs-on: ubuntu-24.04
     container: apache/gluten:centos-9-jdk8
     steps:
@@ -1207,6 +1213,7 @@ jobs:
         run: |
           df -a
           bash dev/ci-velox-buildshared-centos-9.sh
+          cmake --build cpp/build --target java_exception_jni_test --parallel 2
           ccache -s
       # Runs in this job because clang-tidy needs the compilation database and 
header tree
       # the build just produced; only 'cpp/build/' is uploaded, so shipping
@@ -1250,7 +1257,7 @@ jobs:
           --conf $(realpath 
backends-velox/generated-native-benchmark/conf_12_0_*.ini) \
           --plan $(realpath 
backends-velox/generated-native-benchmark/plan_12_0_*.json) \
           --data $(realpath 
backends-velox/generated-native-benchmark/data_12_0_*_0.parquet),$(realpath 
backends-velox/generated-native-benchmark/data_12_0_*_1.parquet)
-      - name: Run UDF test
+      - name: Run JNI and UDF tests
         run: |
           export SPARK_SCALA_VERSION=2.12
           yum install -y java-17-openjdk-devel
@@ -1259,6 +1266,7 @@ jobs:
           java -version
           # Depends on --build_example=ON.
           $MVN_CMD install -Pspark-3.5 -Pbackends-velox -Pjava-17 -pl 
backends-velox -am -DskipTests
+          $MVN_CMD test -pl gluten-arrow -Pspark-3.5 -Pbackends-velox 
-Pjava-17 -Pjni-test
           for bypass_registration in false true; do
             for suite in VeloxUdfSuiteLocal VeloxUdfSuiteCluster; do
               echo "Running $suite with bypass 
registration=$bypass_registration"
diff --git a/cpp/core/CMakeLists.txt b/cpp/core/CMakeLists.txt
index b16ce48c96..6033bc3848 100644
--- a/cpp/core/CMakeLists.txt
+++ b/cpp/core/CMakeLists.txt
@@ -146,6 +146,7 @@ set(SPARK_COLUMNAR_PLUGIN_SRCS
     utils/tac/TypeAwareCompressCodec.cc
     utils/StringUtil.cc
     utils/ObjectStore.cc
+    jni/JavaException.cc
     jni/JniError.cc
     jni/JniCommon.cc
     jni/TaskContextJniWrapper.cc)
@@ -261,6 +262,16 @@ if(NOT ENABLE_GLUTEN_VCPKG)
 endif()
 target_link_libraries(gluten_core_impl PRIVATE glog::glog)
 
+# Java CI builds this explicitly and transfers it separately from production
+# libraries.
+add_library(java_exception_jni_test SHARED EXCLUDE_FROM_ALL
+            tests/JavaExceptionJniTest.cc)
+target_link_libraries(java_exception_jni_test
+                      PRIVATE gluten_core_impl glog::glog Threads::Threads)
+set_target_properties(
+  java_exception_jni_test PROPERTIES LIBRARY_OUTPUT_DIRECTORY
+                                     ${root_directory}/test-libs)
+
 install(TARGETS gluten DESTINATION ${CMAKE_INSTALL_LIBDIR})
 
 if(CMAKE_SYSTEM_NAME MATCHES "Linux")
diff --git a/cpp/core/jni/JavaException.cc b/cpp/core/jni/JavaException.cc
new file mode 100644
index 0000000000..22070a1e3e
--- /dev/null
+++ b/cpp/core/jni/JavaException.cc
@@ -0,0 +1,198 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include "JavaException.h"
+
+#include <glog/logging.h>
+
+#include <stdexcept>
+#include <string>
+
+namespace gluten {
+
+JniEntryGuard::JniEntryGuard() noexcept {
+  ++depth_;
+}
+
+JniEntryGuard::~JniEntryGuard() noexcept {
+  --depth_;
+}
+
+bool JniEntryGuard::isActive() noexcept {
+  return depth_ != 0;
+}
+
+namespace {
+
+// The describer class and result need two locals; reserve one spare slot.
+constexpr jint kDescriptionLocalCapacity = 3;
+
+class LocalFrame {
+ public:
+  explicit LocalFrame(JNIEnv* env) : env_(env), 
pushed_(env->PushLocalFrame(kDescriptionLocalCapacity) == JNI_OK) {}
+
+  ~LocalFrame() {
+    if (pushed_) {
+      env_->PopLocalFrame(nullptr);
+    }
+  }
+
+  bool pushed() const {
+    return pushed_;
+  }
+
+ private:
+  JNIEnv* env_;
+  bool pushed_;
+};
+
+// Lossy native wrappers and destructor logging may have only what(), not the 
carrier.
+std::string describe(JNIEnv* env, jthrowable throwable) {
+  const std::string prefix = "Error during calling Java code from native code: 
";
+  const auto unavailable = [&](const char* reason) {
+    // Describing an exception must not replace the throwable we are 
transporting.
+    env->ExceptionClear();
+    return prefix + "Java stack trace unavailable (" + reason + ")";
+  };
+  LocalFrame frame(env);
+  if (!frame.pushed()) {
+    return unavailable("PushLocalFrame failed");
+  }
+  auto describer = 
env->FindClass("org/apache/gluten/exception/JniExceptionDescriber");
+  if (describer == nullptr) {
+    return unavailable("JniExceptionDescriber lookup failed");
+  }
+  auto method = env->GetStaticMethodID(describer, "describe", 
"(Ljava/lang/Throwable;)Ljava/lang/String;");
+  if (method == nullptr) {
+    return unavailable("describe method lookup failed");
+  }
+  auto description = 
static_cast<jstring>(env->CallStaticObjectMethod(describer, method, throwable));
+  if (env->ExceptionCheck() || description == nullptr) {
+    return unavailable("describe method failed");
+  }
+  const auto release = [&](const char* chars) { 
env->ReleaseStringUTFChars(description, chars); };
+  std::unique_ptr<const char, decltype(release)> 
chars(env->GetStringUTFChars(description, nullptr), release);
+  if (!chars) {
+    return unavailable("GetStringUTFChars failed");
+  }
+  return prefix + chars.get();
+}
+
+} // namespace
+
+struct JavaException::State {
+  State(JNIEnv* env, jthrowable throwable) {
+    if (throwable == nullptr) {
+      throw std::invalid_argument("JavaException requires a non-null 
throwable");
+    }
+    if (env->GetJavaVM(&vm) != JNI_OK) {
+      throw std::runtime_error("Unable to get JavaVM for Java exception");
+    }
+    ref = static_cast<jthrowable>(env->NewGlobalRef(throwable));
+    if (ref == nullptr) {
+      throw std::runtime_error("Unable to create global reference for Java 
exception");
+    }
+  }
+
+  ~State() {
+    JNIEnv* env = nullptr;
+    auto status = vm->GetEnv(reinterpret_cast<void**>(&env), JNI_VERSION_1_8);
+    const bool detached = status == JNI_EDETACHED;
+    if (detached) {
+      status = vm->AttachCurrentThreadAsDaemon(reinterpret_cast<void**>(&env), 
nullptr);
+    }
+    if (status != JNI_OK) {
+      LOG(ERROR) << "Unable to attach thread to release Java exception global 
reference: " << status;
+      return;
+    }
+    env->DeleteGlobalRef(ref);
+    // Only detach if this destructor attached the thread; never detach a 
caller's JNI/HDFS thread.
+    if (detached && vm->DetachCurrentThread() != JNI_OK) {
+      LOG(ERROR) << "Unable to detach thread after releasing Java exception 
global reference";
+    }
+  }
+
+  JavaVM* vm{nullptr};
+  jthrowable ref{nullptr};
+  std::string message;
+};
+
+JavaException::JavaException(JNIEnv* env, jthrowable throwable) : 
state_(std::make_shared<State>(env, throwable)) {
+  try {
+    state_->message = describe(env, throwable);
+  } catch (const std::exception&) {
+    // Keep the captured throwable even if diagnostics fail. what() must not 
allocate a fallback.
+    env->ExceptionClear();
+  }
+}
+
+const char* JavaException::what() const noexcept {
+  return state_->message.empty()
+      ? "Error during calling Java code from native code: Java stack trace 
unavailable (native diagnostic failure)"
+      : state_->message.c_str();
+}
+
+void JavaException::throwToJava(JNIEnv* env) const noexcept {
+  if (env->Throw(state_->ref) != JNI_OK) {
+    LOG(ERROR) << "Unable to restore original Java exception";
+  }
+}
+
+bool JavaException::throwNestedToJava(JNIEnv* env, const std::exception& 
error) noexcept {
+  const auto* nested = dynamic_cast<const std::nested_exception*>(&error);
+  if (nested == nullptr || nested->nested_ptr() == nullptr) {
+    return false;
+  }
+  try {
+    std::rethrow_exception(nested->nested_ptr());
+  } catch (const JavaException& original) {
+    original.throwToJava(env);
+    return true;
+  } catch (const std::exception& cause) {
+    return throwNestedToJava(env, cause);
+  } catch (...) {
+    // Not a Java exception. Leave the enclosing native error to the existing 
JNI fallback.
+    return false;
+  }
+}
+
+void JavaException::check(JNIEnv* env) {
+  if (!env->ExceptionCheck()) {
+    return;
+  }
+  auto throwable = env->ExceptionOccurred();
+  env->ExceptionClear();
+  const auto release = [env](jthrowable ref) { env->DeleteLocalRef(ref); };
+  std::unique_ptr<_jthrowable, decltype(release)> local(throwable, release);
+  // Guard construction only: successful carrier propagation must leave JNI 
clear.
+  auto error = [env, throwable]() {
+    try {
+      return JavaException(env, throwable);
+    } catch (...) {
+      if (!JniEntryGuard::isActive()) {
+        // An attached pool worker has no Java return boundary to consume 
pending state.
+        env->ExceptionClear();
+      } else if (!env->ExceptionCheck() && env->Throw(throwable) != JNI_OK) {
+        LOG(ERROR) << "Unable to restore original Java exception";
+      }
+      throw;
+    }
+  }();
+  throw error;
+}
+
+} // namespace gluten
diff --git a/cpp/core/jni/JavaException.h b/cpp/core/jni/JavaException.h
new file mode 100644
index 0000000000..e1048172b4
--- /dev/null
+++ b/cpp/core/jni/JavaException.h
@@ -0,0 +1,62 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+
+#include <jni.h>
+
+#include <exception>
+#include <memory>
+
+namespace gluten {
+
+// Tracks guarded Java-to-native entries on the current thread, not throwable 
ownership.
+class JniEntryGuard final {
+ public:
+  JniEntryGuard() noexcept;
+  ~JniEntryGuard() noexcept;
+
+  JniEntryGuard(const JniEntryGuard&) = delete;
+  JniEntryGuard& operator=(const JniEntryGuard&) = delete;
+
+  static bool isActive() noexcept;
+
+ private:
+  // Core objects can appear in multiple DSOs; inline storage is coalesced 
across them.
+  inline static thread_local unsigned depth_ = 0;
+};
+
+// Owns a global reference, so copies and exception_ptrs may outlive the JNI 
call or thread.
+class JavaException final : public std::exception {
+ public:
+  // The caller owns throwable's reference and must clear any pending JNI 
exception first.
+  JavaException(JNIEnv* env, jthrowable throwable);
+
+  const char* what() const noexcept override;
+
+  void throwToJava(JNIEnv* env) const noexcept;
+
+  static bool throwNestedToJava(JNIEnv* env, const std::exception& error) 
noexcept;
+
+  static void check(JNIEnv* env);
+
+ private:
+  struct State;
+  std::shared_ptr<State> state_;
+};
+
+} // namespace gluten
diff --git a/cpp/core/jni/JniCommon.h b/cpp/core/jni/JniCommon.h
index f1113a7f82..b72fd3eee9 100644
--- a/cpp/core/jni/JniCommon.h
+++ b/cpp/core/jni/JniCommon.h
@@ -24,6 +24,7 @@
 
 #include <functional>
 
+#include "JavaException.h"
 #include "compute/ProtobufUtils.h"
 #include "compute/Runtime.h"
 #include "memory/AllocationListener.h"
@@ -53,32 +54,7 @@ static inline std::string jStringToCString(JNIEnv* env, 
jstring string) {
 }
 
 static inline void checkException(JNIEnv* env) {
-  if (env->ExceptionCheck()) {
-    jthrowable t = env->ExceptionOccurred();
-    env->ExceptionClear();
-
-    jclass describerClass = 
env->FindClass("org/apache/gluten/exception/JniExceptionDescriber");
-    jmethodID describeMethod =
-        env->GetStaticMethodID(describerClass, "describe", 
"(Ljava/lang/Throwable;)Ljava/lang/String;");
-
-    std::stringstream message;
-    message << "Error during calling Java code from native code: ";
-
-    const auto description = 
static_cast<jstring>(env->CallStaticObjectMethod(describerClass, 
describeMethod, t));
-
-    if (env->ExceptionCheck()) {
-      message << "Uncaught Java exception during calling the Java exception 
describer method!";
-      env->ExceptionClear();
-    } else {
-      try {
-        message << jStringToCString(env, description);
-      } catch (const std::exception& e) {
-        message << e.what();
-      }
-    }
-
-    throw gluten::GlutenException(message.str());
-  }
+  gluten::JavaException::check(env);
 }
 
 static inline jclass createGlobalClassReference(JNIEnv* env, const char* 
className) {
diff --git a/cpp/core/jni/JniError.h b/cpp/core/jni/JniError.h
index 1c57dc3b34..2e09e82f54 100644
--- a/cpp/core/jni/JniError.h
+++ b/cpp/core/jni/JniError.h
@@ -23,16 +23,34 @@
 #include "utils/Exception.h"
 
 #ifndef JNI_METHOD_START
-#define JNI_METHOD_START try {
+#define JNI_METHOD_START                     \
+  const gluten::JniEntryGuard jniEntryGuard; \
+  try {
 // macro ended
 #endif
 
 #ifndef JNI_METHOD_END
-#define JNI_METHOD_END(fallback_expr)                                          
  \
-  }                                                                            
  \
-  catch (std::exception & e) {                                                 
  \
-    env->ThrowNew(gluten::getJniErrorState()->glutenExceptionClass(), 
e.what()); \
-    return fallback_expr;                                                      
  \
+#define JNI_METHOD_END(fallback_expr)                                          
                  \
+  }                                                                            
                  \
+  catch (const gluten::JavaException& e) {                                     
                  \
+    if (!env->ExceptionCheck()) {                                              
                  \
+      e.throwToJava(env);                                                      
                  \
+    }                                                                          
                  \
+    if (!env->ExceptionCheck() &&                                              
                  \
+        env->ThrowNew(gluten::getJniErrorState()->glutenExceptionClass(), 
e.what()) != JNI_OK) { \
+      LOG(ERROR) << "Unable to throw GlutenException at JNI boundary";         
                  \
+    }                                                                          
                  \
+    return fallback_expr;                                                      
                  \
+  }                                                                            
                  \
+  catch (const std::exception& e) {                                            
                  \
+    if (!env->ExceptionCheck()) {                                              
                  \
+      gluten::JavaException::throwNestedToJava(env, e);                        
                  \
+    }                                                                          
                  \
+    if (!env->ExceptionCheck() &&                                              
                  \
+        env->ThrowNew(gluten::getJniErrorState()->glutenExceptionClass(), 
e.what()) != JNI_OK) { \
+      LOG(ERROR) << "Unable to throw GlutenException at JNI boundary";         
                  \
+    }                                                                          
                  \
+    return fallback_expr;                                                      
                  \
   }
 // macro ended
 #endif
diff --git a/cpp/core/tests/CMakeLists.txt b/cpp/core/tests/CMakeLists.txt
index 26000453f6..26ae2bc47d 100644
--- a/cpp/core/tests/CMakeLists.txt
+++ b/cpp/core/tests/CMakeLists.txt
@@ -19,3 +19,6 @@ add_test_case(memory_allocator_test SOURCES 
MemoryAllocatorTest.cc)
 add_test_case(ffor_codec_test SOURCES FForCodecTest.cc)
 add_test_case(print_config_test SOURCES PrintConfigTest.cc)
 add_test_case(payload_test SOURCES PayloadTest.cc)
+add_test_case(java_exception_test SOURCES JavaExceptionTest.cc)
+add_test_case(java_exception_allocation_test SOURCES
+              JavaExceptionAllocationTest.cc)
diff --git a/cpp/core/tests/JavaExceptionAllocationTest.cc 
b/cpp/core/tests/JavaExceptionAllocationTest.cc
new file mode 100644
index 0000000000..ca150cc1d6
--- /dev/null
+++ b/cpp/core/tests/JavaExceptionAllocationTest.cc
@@ -0,0 +1,160 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include <gtest/gtest.h>
+
+#include <cstdlib>
+#include <new>
+#include <utility>
+
+#include "jni/JavaException.h"
+#include "tests/utils/TestJniEnvironment.h"
+
+namespace {
+thread_local bool failNextAllocation = false;
+
+struct RestoreJniFunctions {
+  JNIEnv* env;
+  const JNINativeInterface_* original;
+
+  ~RestoreJniFunctions() {
+    env->functions = original;
+  }
+};
+} // namespace
+
+// This executable isolates the replacement allocator from other core tests.
+void* operator new(std::size_t size) {
+  if (std::exchange(failNextAllocation, false)) {
+    throw std::bad_alloc();
+  }
+  if (auto* memory = std::malloc(size == 0 ? 1 : size)) {
+    return memory;
+  }
+  throw std::bad_alloc();
+}
+
+void operator delete(void* memory) noexcept {
+  std::free(memory);
+}
+
+void operator delete(void* memory, std::size_t) noexcept {
+  std::free(memory);
+}
+
+TEST(JavaExceptionAllocationTest, stateAllocationFailureRetainsOriginal) {
+  gluten::TestJniEnvironment jni;
+  const gluten::JniEntryGuard entry;
+  jni.pending = &jni.original;
+  failNextAllocation = true;
+  try {
+    gluten::JavaException::check(jni.env());
+    failNextAllocation = false;
+    FAIL() << "Expected std::bad_alloc";
+  } catch (const std::bad_alloc&) {
+    EXPECT_FALSE(std::exchange(failNextAllocation, false));
+  } catch (...) {
+    failNextAllocation = false;
+    throw;
+  }
+  EXPECT_EQ(jni.pending, &jni.original);
+  EXPECT_EQ(jni.createdGlobalRefs, 0);
+  EXPECT_EQ(jni.deletedGlobalRefs, 0);
+  EXPECT_EQ(jni.deletedLocalRefs, 1);
+  EXPECT_EQ(jni.pushedFrames, 0);
+  EXPECT_EQ(jni.poppedFrames, 0);
+  EXPECT_EQ(jni.releasedStrings, 0);
+}
+
+TEST(JavaExceptionAllocationTest, 
workerStateAllocationFailureLeavesNoPendingException) {
+  gluten::TestJniEnvironment jni;
+  const gluten::JniEntryGuard callerEntry;
+  jni.workerAttached = true;
+  std::thread worker([&] {
+    EXPECT_FALSE(gluten::JniEntryGuard::isActive());
+    jni.pending = &jni.original;
+    failNextAllocation = true;
+    try {
+      gluten::JavaException::check(jni.workerEnv());
+      failNextAllocation = false;
+      FAIL() << "Expected std::bad_alloc";
+    } catch (const std::bad_alloc&) {
+      EXPECT_FALSE(std::exchange(failNextAllocation, false));
+    }
+    EXPECT_EQ(jni.pending, nullptr);
+    EXPECT_NO_THROW(gluten::JavaException::check(jni.workerEnv()));
+  });
+  worker.join();
+  EXPECT_EQ(jni.deletedLocalRefs, 1);
+  EXPECT_EQ(jni.createdGlobalRefs, 0);
+  EXPECT_EQ(jni.deletedGlobalRefs, 0);
+  EXPECT_EQ(jni.attaches, 0);
+  EXPECT_EQ(jni.detaches, 0);
+}
+
+TEST(JavaExceptionAllocationTest, entryTrackingDoesNotAllocate) {
+  bool nestedActive = false;
+  bool outerActive = false;
+  failNextAllocation = true;
+  {
+    const gluten::JniEntryGuard outer;
+    try {
+      const gluten::JniEntryGuard inner;
+      nestedActive = gluten::JniEntryGuard::isActive();
+      throw 7;
+    } catch (int) {
+      outerActive = gluten::JniEntryGuard::isActive();
+    }
+  }
+  const bool noAllocation = std::exchange(failNextAllocation, false);
+  EXPECT_TRUE(noAllocation);
+  EXPECT_TRUE(nestedActive);
+  EXPECT_TRUE(outerActive);
+  EXPECT_FALSE(gluten::JniEntryGuard::isActive());
+}
+
+TEST(JavaExceptionAllocationTest, diagnosticAllocationFailureRetainsOriginal) {
+  gluten::TestJniEnvironment jni;
+  auto functions = *jni.env()->functions;
+  functions.GetStringUTFChars = [](JNIEnv*, jstring, jboolean*) -> const char* 
{
+    // The throwable is already captured; fail the native diagnostic string, 
not NewGlobalRef.
+    failNextAllocation = true;
+    return "original Java exception";
+  };
+  const RestoreJniFunctions restore{jni.env(), jni.env()->functions};
+  jni.env()->functions = &functions;
+  jni.pending = &jni.original;
+  try {
+    gluten::JavaException::check(jni.env());
+    failNextAllocation = false;
+    FAIL() << "Expected JavaException";
+  } catch (const gluten::JavaException& error) {
+    EXPECT_FALSE(std::exchange(failNextAllocation, false));
+    EXPECT_STREQ(
+        error.what(),
+        "Error during calling Java code from native code: Java stack trace 
unavailable (native diagnostic failure)");
+    EXPECT_EQ(jni.deletedGlobalRefs, 0);
+    auto copy = error;
+    copy.throwToJava(jni.env());
+  }
+  EXPECT_EQ(jni.pending, &jni.original);
+  EXPECT_EQ(jni.createdGlobalRefs, 1);
+  EXPECT_EQ(jni.deletedGlobalRefs, 1);
+  EXPECT_EQ(jni.deletedLocalRefs, 1);
+  EXPECT_EQ(jni.releasedStrings, 1);
+  EXPECT_EQ(jni.pushedFrames, jni.poppedFrames);
+}
diff --git a/cpp/core/tests/JavaExceptionJniTest.cc 
b/cpp/core/tests/JavaExceptionJniTest.cc
new file mode 100644
index 0000000000..353e3a73b7
--- /dev/null
+++ b/cpp/core/tests/JavaExceptionJniTest.cc
@@ -0,0 +1,240 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include <exception>
+#include <stdexcept>
+#include <thread>
+
+#include "jni/JniCommon.h"
+#include "jni/JniError.h"
+
+namespace {
+class ScopedThrowFailure : public JNINativeInterface_ {
+ public:
+  ScopedThrowFailure(JNIEnv* env, jthrowable failure) noexcept
+      : JNINativeInterface_(*env->functions), env_(env), 
original_(env->functions), failure_(failure) {
+    Throw = [](JNIEnv* env, jthrowable) {
+      const auto* functions = static_cast<const 
ScopedThrowFailure*>(env->functions);
+      if (functions->failure_ != nullptr && functions->original_->Throw(env, 
functions->failure_) != JNI_OK) {
+        LOG(ERROR) << "Unable to install injected Java restoration failure";
+      }
+      return JNI_ERR;
+    };
+    env_->functions = this;
+  }
+
+  ~ScopedThrowFailure() {
+    env_->functions = original_;
+  }
+
+  ScopedThrowFailure(const ScopedThrowFailure&) = delete;
+  ScopedThrowFailure& operator=(const ScopedThrowFailure&) = delete;
+
+ private:
+  JNIEnv* env_;
+  const JNINativeInterface_* original_;
+  jthrowable failure_;
+};
+
+class ScopedCaptureFailure : public JNINativeInterface_ {
+ public:
+  ScopedCaptureFailure(JNIEnv* env, jthrowable failure) noexcept
+      : JNINativeInterface_(*env->functions), env_(env), 
original_(env->functions), failure_(failure) {
+    NewGlobalRef = [](JNIEnv* env, jobject) -> jobject {
+      const auto* functions = static_cast<const 
ScopedCaptureFailure*>(env->functions);
+      if (functions->original_->Throw(env, functions->failure_) != JNI_OK) {
+        throw std::runtime_error("Unable to install injected Java capture 
failure");
+      }
+      return nullptr;
+    };
+    env_->functions = this;
+  }
+
+  ~ScopedCaptureFailure() {
+    env_->functions = original_;
+  }
+
+  ScopedCaptureFailure(const ScopedCaptureFailure&) = delete;
+  ScopedCaptureFailure& operator=(const ScopedCaptureFailure&) = delete;
+
+ private:
+  JNIEnv* env_;
+  const JNINativeInterface_* original_;
+  jthrowable failure_;
+};
+
+void invokeCallback(JNIEnv* env, jobject callback) {
+  auto callbackClass = env->GetObjectClass(callback);
+  checkException(env);
+  auto run = env->GetMethodID(callbackClass, "run", "()V");
+  env->DeleteLocalRef(callbackClass);
+  checkException(env);
+  env->CallVoidMethod(callback, run);
+  checkException(env);
+}
+
+jint roundTrip(JNIEnv* env, jobject callback, jboolean nested, jthrowable 
pending) {
+  JNI_METHOD_START
+  gluten::getJniErrorState()->ensureInitialized(env);
+  checkException(env);
+  try {
+    invokeCallback(env, callback);
+  } catch (...) {
+    if (pending != nullptr && env->Throw(pending) != JNI_OK) {
+      throw std::runtime_error("Unable to install newer pending Java 
exception");
+    }
+    if (nested) {
+      std::throw_with_nested(std::runtime_error("native wrapper"));
+    }
+    throw;
+  }
+  return 42;
+  JNI_METHOD_END(-1)
+}
+} // namespace
+
+extern "C" JNIEXPORT jint JNICALL
+Java_org_apache_gluten_jni_JavaExceptionJniTest_roundTrip(JNIEnv* env, jclass, 
jobject callback, jboolean nested) {
+  return roundTrip(env, callback, nested, nullptr);
+}
+
+extern "C" JNIEXPORT jint JNICALL 
Java_org_apache_gluten_jni_JavaExceptionJniTest_roundTripWithPendingException(
+    JNIEnv* env,
+    jclass,
+    jobject callback,
+    jboolean nested,
+    jthrowable pending) {
+  return roundTrip(env, callback, nested, pending);
+}
+
+extern "C" JNIEXPORT void JNICALL 
Java_org_apache_gluten_jni_JavaExceptionJniTest_roundTripWithFailedCapture(
+    JNIEnv* env,
+    jclass,
+    jobject callback,
+    jthrowable failure) {
+  JNI_METHOD_START
+  gluten::getJniErrorState()->ensureInitialized(env);
+  checkException(env);
+  const ScopedCaptureFailure functions(env, failure);
+  invokeCallback(env, callback);
+  JNI_METHOD_END()
+}
+
+extern "C" JNIEXPORT void JNICALL 
Java_org_apache_gluten_jni_JavaExceptionJniTest_roundTripOnWorker(
+    JNIEnv* env,
+    jclass,
+    jobject callback,
+    jobject nextCallback,
+    jthrowable captureFailure) {
+  JNI_METHOD_START
+  gluten::getJniErrorState()->ensureInitialized(env);
+  checkException(env);
+  JavaVM* vm = nullptr;
+  if (env->GetJavaVM(&vm) != JNI_OK) {
+    throw std::runtime_error("Unable to get test JavaVM");
+  }
+  const auto release = [env](jobject ref) { env->DeleteGlobalRef(ref); };
+  const auto retain = [&](jobject object) {
+    std::unique_ptr<_jobject, decltype(release)> 
ref(env->NewGlobalRef(object), release);
+    checkException(env);
+    return ref;
+  };
+  auto globalCallback = retain(callback);
+  auto globalNextCallback = retain(nextCallback);
+  auto globalFailure = retain(captureFailure);
+  std::exception_ptr error;
+  std::thread worker([&] {
+    JNIEnv* workerEnv = nullptr;
+    if (vm->AttachCurrentThreadAsDaemon(reinterpret_cast<void**>(&workerEnv), 
nullptr) != JNI_OK) {
+      error = std::make_exception_ptr(std::runtime_error("Unable to attach 
test worker"));
+      return;
+    }
+    try {
+      if (gluten::JniEntryGuard::isActive()) {
+        throw std::runtime_error("Worker inherited another thread's JNI 
entry");
+      }
+      try {
+        if (globalFailure) {
+          const ScopedCaptureFailure functions(workerEnv, 
static_cast<jthrowable>(globalFailure.get()));
+          invokeCallback(workerEnv, globalCallback.get());
+        } else {
+          invokeCallback(workerEnv, globalCallback.get());
+        }
+      } catch (const gluten::JavaException& captured) {
+        auto copy = captured;
+        error = std::make_exception_ptr(copy);
+      } catch (...) {
+        error = std::current_exception();
+      }
+      if (workerEnv->ExceptionCheck()) {
+        workerEnv->ExceptionClear();
+        throw std::runtime_error("Capture failure left a pending exception on 
a reused worker");
+      }
+      JNIEnv* reusedEnv = nullptr;
+      if (vm->GetEnv(reinterpret_cast<void**>(&reusedEnv), JNI_VERSION_1_8) != 
JNI_OK || reusedEnv != workerEnv) {
+        throw std::runtime_error("Worker was detached between callbacks");
+      }
+      invokeCallback(workerEnv, globalNextCallback.get());
+      if (gluten::JniEntryGuard::isActive()) {
+        throw std::runtime_error("Worker retained a completed JNI entry");
+      }
+    } catch (...) {
+      error = std::current_exception();
+    }
+    // This test owns the thread; detach only after both callbacks, not 
between jobs.
+    workerEnv->ExceptionClear();
+    if (vm->DetachCurrentThread() != JNI_OK) {
+      error = std::make_exception_ptr(std::runtime_error("Unable to detach 
finished test worker"));
+    }
+  });
+  worker.join();
+  if (error) {
+    std::rethrow_exception(error);
+  }
+  JNI_METHOD_END()
+}
+
+extern "C" JNIEXPORT jint JNICALL 
Java_org_apache_gluten_jni_JavaExceptionJniTest_roundTripWithFailedRestore(
+    JNIEnv* env,
+    jclass clazz,
+    jobject callback,
+    jboolean nested,
+    jthrowable failure) {
+  // Keep fault injection active through the production boundary's catch 
handlers.
+  const ScopedThrowFailure functions(env, failure);
+  return Java_org_apache_gluten_jni_JavaExceptionJniTest_roundTrip(env, clazz, 
callback, nested);
+}
+
+extern "C" JNIEXPORT void JNICALL
+Java_org_apache_gluten_jni_JavaExceptionJniTest_throwNativeException(JNIEnv* 
env, jclass) {
+  JNI_METHOD_START
+  gluten::getJniErrorState()->ensureInitialized(env);
+  checkException(env);
+  throw std::runtime_error("native-only failure");
+  JNI_METHOD_END()
+}
+
+extern "C" JNIEXPORT void JNICALL 
Java_org_apache_gluten_jni_JavaExceptionJniTest_close(JNIEnv* env, jclass) {
+  JNI_METHOD_START
+  gluten::getJniErrorState()->close();
+  JNI_METHOD_END()
+}
+
+extern "C" JNIEXPORT jboolean JNICALL 
Java_org_apache_gluten_jni_JavaExceptionJniTest_entryActive(JNIEnv*, jclass) {
+  // Inspect the caller's scope without adding another guarded entry.
+  return gluten::JniEntryGuard::isActive();
+}
diff --git a/cpp/core/tests/JavaExceptionTest.cc 
b/cpp/core/tests/JavaExceptionTest.cc
new file mode 100644
index 0000000000..c01708dfb4
--- /dev/null
+++ b/cpp/core/tests/JavaExceptionTest.cc
@@ -0,0 +1,196 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include <gtest/gtest.h>
+
+#include <stdexcept>
+#include <string>
+
+#include "jni/JavaException.h"
+#include "tests/utils/TestJniEnvironment.h"
+
+using namespace gluten;
+
+TEST(JavaExceptionTest, noPendingException) {
+  TestJniEnvironment jni;
+  EXPECT_NO_THROW(JavaException::check(jni.env()));
+  EXPECT_EQ(jni.createdGlobalRefs, 0);
+}
+
+TEST(JavaExceptionTest, copiesKeepOriginalAliveUntilLastRelease) {
+  TestJniEnvironment jni;
+  std::exception_ptr saved;
+  jni.pending = &jni.original;
+  try {
+    JavaException::check(jni.env());
+    FAIL() << "Expected JavaException";
+  } catch (const JavaException& error) {
+    EXPECT_EQ(jni.pending, nullptr);
+    EXPECT_EQ(jni.deletedLocalRefs, 1);
+    EXPECT_STREQ(error.what(), "Error during calling Java code from native 
code: original Java exception");
+    auto copy = error;
+    saved = std::make_exception_ptr(copy);
+  }
+  EXPECT_EQ(jni.createdGlobalRefs, 1);
+  EXPECT_EQ(jni.deletedGlobalRefs, 0);
+  try {
+    std::rethrow_exception(saved);
+  } catch (const JavaException& error) {
+    error.throwToJava(jni.env());
+  }
+  EXPECT_EQ(jni.pending, &jni.original);
+  saved = nullptr;
+  EXPECT_EQ(jni.deletedGlobalRefs, 1);
+  EXPECT_TRUE(jni.globalRefs.empty());
+  EXPECT_EQ(jni.pushedFrames, jni.poppedFrames);
+  EXPECT_EQ(jni.releasedStrings, 1);
+  EXPECT_EQ(jni.attaches, 0);
+  EXPECT_EQ(jni.detaches, 0);
+}
+
+TEST(JavaExceptionTest, cleanupOnDetachedThread) {
+  TestJniEnvironment jni;
+  auto saved = std::make_exception_ptr(JavaException(jni.env(), 
&jni.original));
+  std::thread worker([error = std::move(saved)]() mutable { error = nullptr; 
});
+  worker.join();
+  EXPECT_EQ(jni.deletedGlobalRefs, 1);
+  EXPECT_TRUE(jni.globalRefs.empty());
+  EXPECT_EQ(jni.deletingEnv, jni.workerEnv());
+  EXPECT_EQ(jni.attaches, 1);
+  EXPECT_EQ(jni.detaches, 1);
+}
+
+TEST(JavaExceptionTest, cleanupDoesNotDetachPreviouslyAttachedThread) {
+  TestJniEnvironment jni;
+  jni.workerAttached = true;
+  auto saved = std::make_exception_ptr(JavaException(jni.env(), 
&jni.original));
+  std::thread worker([error = std::move(saved)]() mutable { error = nullptr; 
});
+  worker.join();
+  EXPECT_EQ(jni.deletedGlobalRefs, 1);
+  EXPECT_EQ(jni.deletingEnv, jni.workerEnv());
+  EXPECT_EQ(jni.attaches, 0);
+  EXPECT_EQ(jni.detaches, 0);
+}
+
+TEST(JavaExceptionTest, descriptionFailureDoesNotReplaceOriginal) {
+  TestJniEnvironment jni;
+  jni.failDescription = true;
+  jni.pending = &jni.original;
+  try {
+    JavaException::check(jni.env());
+    FAIL() << "Expected JavaException";
+  } catch (const JavaException& error) {
+    EXPECT_EQ(jni.pending, nullptr);
+    EXPECT_NE(std::string(error.what()).find("JniExceptionDescriber lookup 
failed"), std::string::npos);
+    error.throwToJava(jni.env());
+  }
+  EXPECT_EQ(jni.pending, &jni.original);
+  EXPECT_EQ(jni.deletedGlobalRefs, 1);
+  EXPECT_EQ(jni.deletedLocalRefs, 1);
+  EXPECT_EQ(jni.pushedFrames, jni.poppedFrames);
+}
+
+TEST(JavaExceptionTest, localFrameFailureDoesNotReplaceOriginal) {
+  TestJniEnvironment jni;
+  jni.failLocalFrame = true;
+  {
+    JavaException error(jni.env(), &jni.original);
+    EXPECT_EQ(jni.pending, nullptr);
+    error.throwToJava(jni.env());
+  }
+  EXPECT_EQ(jni.pending, &jni.original);
+  EXPECT_EQ(jni.deletedGlobalRefs, 1);
+  EXPECT_EQ(jni.poppedFrames, 0);
+}
+
+TEST(JavaExceptionTest, globalRefFailureRetainsPendingAllocationError) {
+  TestJniEnvironment jni;
+  const JniEntryGuard entry;
+  jni.failGlobalRef = true;
+  jni.pending = &jni.original;
+  EXPECT_THROW(JavaException::check(jni.env()), std::runtime_error);
+  EXPECT_EQ(jni.pending, &jni.secondary);
+  EXPECT_EQ(jni.deletedLocalRefs, 1);
+  EXPECT_EQ(jni.createdGlobalRefs, 0);
+  EXPECT_EQ(jni.deletedGlobalRefs, 0);
+}
+
+TEST(JavaExceptionTest, workerGlobalRefFailureLeavesNoPendingException) {
+  TestJniEnvironment jni;
+  const JniEntryGuard callerEntry;
+  jni.workerAttached = true;
+  std::thread worker([&] {
+    EXPECT_FALSE(JniEntryGuard::isActive());
+    jni.failGlobalRef = true;
+    jni.pending = &jni.original;
+    EXPECT_THROW(JavaException::check(jni.workerEnv()), std::runtime_error);
+    EXPECT_EQ(jni.pending, nullptr);
+    jni.failGlobalRef = false;
+    EXPECT_NO_THROW(JavaException::check(jni.workerEnv()));
+  });
+  worker.join();
+  EXPECT_EQ(jni.deletedLocalRefs, 1);
+  EXPECT_EQ(jni.createdGlobalRefs, 0);
+  EXPECT_EQ(jni.deletedGlobalRefs, 0);
+  EXPECT_EQ(jni.attaches, 0);
+  EXPECT_EQ(jni.detaches, 0);
+}
+
+TEST(JavaExceptionTest, standardNestedWrappersRestoreOriginal) {
+  TestJniEnvironment jni;
+  try {
+    throw JavaException(jni.env(), &jni.original);
+  } catch (...) {
+    try {
+      std::throw_with_nested(std::runtime_error("inner native wrapper"));
+    } catch (...) {
+      try {
+        std::throw_with_nested(std::runtime_error("outer native wrapper"));
+      } catch (const std::exception& error) {
+        EXPECT_TRUE(JavaException::throwNestedToJava(jni.env(), error));
+      }
+    }
+  }
+  EXPECT_EQ(jni.pending, &jni.original);
+  EXPECT_EQ(jni.createdGlobalRefs, 1);
+  EXPECT_EQ(jni.deletedGlobalRefs, 1);
+}
+
+TEST(JavaExceptionTest, nativeOnlyWrappersRetainExistingFallback) {
+  TestJniEnvironment jni;
+  EXPECT_FALSE(JavaException::throwNestedToJava(jni.env(), 
std::runtime_error("native error")));
+  try {
+    throw std::runtime_error("native cause");
+  } catch (...) {
+    try {
+      std::throw_with_nested(std::runtime_error("native wrapper"));
+    } catch (const std::exception& error) {
+      EXPECT_FALSE(JavaException::throwNestedToJava(jni.env(), error));
+    }
+  }
+  try {
+    throw 42;
+  } catch (...) {
+    try {
+      std::throw_with_nested(std::runtime_error("nonstandard native cause"));
+    } catch (const std::exception& error) {
+      EXPECT_FALSE(JavaException::throwNestedToJava(jni.env(), error));
+    }
+  }
+  EXPECT_EQ(jni.pending, nullptr);
+  EXPECT_EQ(jni.createdGlobalRefs, 0);
+}
diff --git a/cpp/core/tests/utils/TestJniEnvironment.h 
b/cpp/core/tests/utils/TestJniEnvironment.h
new file mode 100644
index 0000000000..f339fe750a
--- /dev/null
+++ b/cpp/core/tests/utils/TestJniEnvironment.h
@@ -0,0 +1,179 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+
+#include <jni.h>
+
+#include <thread>
+#include <unordered_map>
+
+namespace gluten {
+
+// JNI function tables let tests account for references without relying on JVM 
garbage collection.
+class TestJniEnvironment {
+ private:
+  struct Env : JNIEnv_ {
+    explicit Env(TestJniEnvironment* owner) : owner(owner) {
+      functions = &owner->functions_;
+    }
+    TestJniEnvironment* owner;
+  };
+
+  struct Vm : JavaVM_ {
+    explicit Vm(TestJniEnvironment* owner) : owner(owner) {
+      functions = &owner->invocation_;
+    }
+    TestJniEnvironment* owner;
+  };
+
+  static TestJniEnvironment& from(JNIEnv* env) {
+    return *static_cast<Env*>(env)->owner;
+  }
+
+  static TestJniEnvironment& from(JavaVM* vm) {
+    return *static_cast<Vm*>(vm)->owner;
+  }
+
+ public:
+  TestJniEnvironment() {
+    functions_.GetJavaVM = [](JNIEnv* env, JavaVM** vm) {
+      *vm = &from(env).vm_;
+      return JNI_OK;
+    };
+    functions_.ExceptionCheck = [](JNIEnv* env) -> jboolean { return 
from(env).pending != nullptr; };
+    functions_.ExceptionOccurred = [](JNIEnv* env) { return from(env).pending; 
};
+    functions_.ExceptionClear = [](JNIEnv* env) { from(env).pending = nullptr; 
};
+    functions_.NewGlobalRef = [](JNIEnv* env, jobject object) -> jobject {
+      auto& self = from(env);
+      if (self.failGlobalRef) {
+        self.pending = &self.secondary;
+        return nullptr;
+      }
+      auto ref = new _jthrowable();
+      self.globalRefs.emplace(ref, static_cast<jthrowable>(object));
+      ++self.createdGlobalRefs;
+      return ref;
+    };
+    functions_.DeleteGlobalRef = [](JNIEnv* env, jobject object) {
+      auto& self = from(env);
+      self.globalRefs.erase(object);
+      delete static_cast<jthrowable>(object);
+      ++self.deletedGlobalRefs;
+      self.deletingEnv = env;
+    };
+    functions_.DeleteLocalRef = [](JNIEnv* env, jobject) { 
++from(env).deletedLocalRefs; };
+    functions_.Throw = [](JNIEnv* env, jthrowable throwable) {
+      auto& self = from(env);
+      auto global = self.globalRefs.find(throwable);
+      self.pending = global == self.globalRefs.end() ? throwable : 
global->second;
+      return JNI_OK;
+    };
+    functions_.PushLocalFrame = [](JNIEnv* env, jint) {
+      auto& self = from(env);
+      if (self.failLocalFrame) {
+        self.pending = &self.secondary;
+        return JNI_ERR;
+      }
+      ++self.pushedFrames;
+      return JNI_OK;
+    };
+    functions_.PopLocalFrame = [](JNIEnv* env, jobject result) {
+      ++from(env).poppedFrames;
+      return result;
+    };
+    functions_.FindClass = [](JNIEnv* env, const char*) -> jclass {
+      auto& self = from(env);
+      if (self.failDescription) {
+        self.pending = &self.secondary;
+        return nullptr;
+      }
+      return &self.describer_;
+    };
+    functions_.GetStaticMethodID = [](JNIEnv* env, jclass, const char*, const 
char*) {
+      return reinterpret_cast<jmethodID>(&from(env).describer_);
+    };
+    functions_.CallStaticObjectMethodV = [](JNIEnv* env, jclass, jmethodID, 
va_list) -> jobject {
+      return &from(env).description_;
+    };
+    functions_.GetStringUTFChars = [](JNIEnv*, jstring, jboolean*) { return 
"original Java exception"; };
+    functions_.ReleaseStringUTFChars = [](JNIEnv* env, jstring, const char*) { 
++from(env).releasedStrings; };
+    invocation_.GetEnv = [](JavaVM* vm, void** env, jint) {
+      auto& self = from(vm);
+      if (std::this_thread::get_id() == self.ownerThread_) {
+        *env = &self.env_;
+        return JNI_OK;
+      }
+      if (!self.workerAttached) {
+        return JNI_EDETACHED;
+      }
+      *env = &self.workerEnv_;
+      return JNI_OK;
+    };
+    invocation_.AttachCurrentThreadAsDaemon = [](JavaVM* vm, void** env, 
void*) {
+      auto& self = from(vm);
+      ++self.attaches;
+      self.workerAttached = true;
+      *env = &self.workerEnv_;
+      return JNI_OK;
+    };
+    invocation_.DetachCurrentThread = [](JavaVM* vm) {
+      auto& self = from(vm);
+      ++self.detaches;
+      self.workerAttached = false;
+      return JNI_OK;
+    };
+  }
+
+  JNIEnv* env() {
+    return &env_;
+  }
+
+  JNIEnv* workerEnv() {
+    return &workerEnv_;
+  }
+
+  _jthrowable original;
+  _jthrowable secondary;
+  jthrowable pending{nullptr};
+  std::unordered_map<jobject, jthrowable> globalRefs;
+  int createdGlobalRefs{0};
+  int deletedGlobalRefs{0};
+  int deletedLocalRefs{0};
+  int pushedFrames{0};
+  int poppedFrames{0};
+  int releasedStrings{0};
+  int attaches{0};
+  int detaches{0};
+  bool workerAttached{false};
+  bool failGlobalRef{false};
+  bool failDescription{false};
+  bool failLocalFrame{false};
+  JNIEnv* deletingEnv{nullptr};
+
+ private:
+  JNINativeInterface_ functions_{};
+  JNIInvokeInterface_ invocation_{};
+  Env env_{this};
+  Env workerEnv_{this};
+  Vm vm_{this};
+  _jclass describer_;
+  _jstring description_;
+  const std::thread::id ownerThread_{std::this_thread::get_id()};
+};
+
+} // namespace gluten
diff --git a/docs/developers/NewToGluten.md b/docs/developers/NewToGluten.md
index f2591918eb..4e8affca0d 100644
--- a/docs/developers/NewToGluten.md
+++ b/docs/developers/NewToGluten.md
@@ -94,6 +94,55 @@ To format Java/Scala code using the 
[Spotless](https://github.com/diffplug/spotl
 ./dev/format-scala-code.sh
 ```
 
+### Java exceptions crossing native code
+
+JNI callbacks must call `checkException(env)` after invoking Java. It throws
+`gluten::JavaException`, which owns a shared global reference to the original 
Java
+throwable. `JNI_METHOD_END` restores that same object with JNI `Throw`, 
retaining
+its class, cause, suppressed exceptions, stack trace, and structured Spark 
error
+metadata. Native diagnostic formatting is best-effort after capturing the 
throwable.
+If native carrier construction fails within a guarded JNI entry on the current
+thread, `checkException` restores the original throwable before local-reference
+cleanup unless a newer Java exception is pending. Without such an entry, it 
clears
+pending JNI state before propagating the native failure so an attached worker 
can
+be reused. Successfully captured carriers remain transferable across threads.
+Successful carrier propagation keeps JNI clear until the return boundary 
restores
+the throwable.
+Do not replace this carrier with an exception constructed from `what()`.
+
+Same-object preservation applies at the JNI return boundary. Public iterator
+`hasNext()`/`next()` may apply existing Java wrappers, usually 
`GlutenException`;
+existing schema-error translation also retains the original as a cause. Inspect
+the cause chain rather than assuming a top-level exception class or 
`SparkThrowable`.
+These wrappers catch `Exception`, not every `Throwable`.
+
+Copies and `std::exception_ptr` instances keep the throwable alive until the 
last
+owner releases it. Cleanup uses the current thread's JNI environment and 
detaches
+only threads it attached itself. Failures while describing the captured 
throwable
+do not replace it; if creating its global reference fails within a guarded JNI
+entry, the pending Java allocation error is preserved.
+
+`JNI_METHOD_END` also restores carriers inside standard `std::nested_exception`
+wrappers. Other native errors keep their existing `GlutenException` fallback.
+If carrier restoration leaves no pending Java exception, the boundary attempts
+that same fallback using the caught exception's diagnostic. A newer pending 
Java
+exception is left untouched; failure to throw the fallback is logged.
+Backend-specific callback and output-boundary propagation is separate from this
+core contract; it does not by itself protect the full Velox driver path.
+Preserving the throwable does not merge Java and C++ frames into a hybrid stack
+trace (see [#9642](https://github.com/apache/gluten/issues/9642)).
+
+`gluten-arrow/src/test/java/org/apache/gluten/jni/JavaExceptionJniTest.java` 
runs
+these cases through JUnit and Maven Surefire without starting Spark or a 
backend.
+After configuring the native core, build its test-only bridge with
+`cmake --build cpp/build --target java_exception_jni_test`, then run
+`./build/mvn test -pl gluten-arrow -Pbackends-velox -Pspark-3.5 -Pjava-17 
-Pjni-test`.
+The explicit `jni-test` profile requires the bridge in `cpp/build/test-libs`;
+a missing library fails the tests rather than skipping them. The existing
+`cpp-test-udf-test` CI job builds the bridge locally and enables this profile 
in
+its Java 17 Maven step. No separate test artifact is needed, and the bridge is
+neither installed nor bundled in production jars.
+
 ### C++ code development
 
 This guide is for remote debugging by connecting to the remote Linux server 
using `SSH`.
diff --git a/gluten-arrow/pom.xml b/gluten-arrow/pom.xml
index 5b5f761c2f..54f8391041 100644
--- a/gluten-arrow/pom.xml
+++ b/gluten-arrow/pom.xml
@@ -278,4 +278,47 @@
     
<testOutputDirectory>target/scala-${scala.binary.version}/test-classes</testOutputDirectory>
   </build>
 
+  <profiles>
+    <profile>
+      <id>exclude-jni-test</id>
+      <activation>
+        <activeByDefault>true</activeByDefault>
+      </activation>
+      <build>
+        <plugins>
+          <plugin>
+            <groupId>org.apache.maven.plugins</groupId>
+            <artifactId>maven-surefire-plugin</artifactId>
+            <configuration>
+              <excludes combine.children="append">
+                <!-- The jni-test profile requires the separately built native 
test bridge. -->
+                <exclude>**/JavaExceptionJniTest.java</exclude>
+              </excludes>
+            </configuration>
+          </plugin>
+        </plugins>
+      </build>
+    </profile>
+    <profile>
+      <id>jni-test</id>
+      <properties>
+        
<gluten.jni.test.lib.dir>${project.basedir}/../cpp/build/test-libs</gluten.jni.test.lib.dir>
+      </properties>
+      <build>
+        <plugins>
+          <plugin>
+            <groupId>org.apache.maven.plugins</groupId>
+            <artifactId>maven-surefire-plugin</artifactId>
+            <configuration>
+              <failIfNoTests>true</failIfNoTests>
+              <forkedProcessTimeoutInSeconds>60</forkedProcessTimeoutInSeconds>
+              <systemPropertyVariables>
+                
<gluten.jni.test.lib.dir>${gluten.jni.test.lib.dir}</gluten.jni.test.lib.dir>
+              </systemPropertyVariables>
+            </configuration>
+          </plugin>
+        </plugins>
+      </build>
+    </profile>
+  </profiles>
 </project>
diff --git 
a/gluten-arrow/src/test/java/org/apache/gluten/jni/JavaExceptionJniTest.java 
b/gluten-arrow/src/test/java/org/apache/gluten/jni/JavaExceptionJniTest.java
new file mode 100644
index 0000000000..154487c462
--- /dev/null
+++ b/gluten-arrow/src/test/java/org/apache/gluten/jni/JavaExceptionJniTest.java
@@ -0,0 +1,310 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.gluten.jni;
+
+import org.apache.gluten.exception.GlutenException;
+
+import org.junit.AfterClass;
+import org.junit.Assert;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.io.File;
+import java.util.Collections;
+import java.util.Map;
+import java.util.concurrent.atomic.AtomicReference;
+import java.util.function.Consumer;
+
+/** Tests the core JNI exception contract without starting Spark or a backend. 
*/
+public final class JavaExceptionJniTest {
+  private static boolean libraryLoaded;
+
+  public interface Callback {
+    void run() throws Throwable;
+  }
+
+  private static final class StructuredException extends RuntimeException {
+    private final String errorClass;
+    private final Map<String, String> parameters;
+
+    private StructuredException(String errorClass, Map<String, String> 
parameters) {
+      this.errorClass = errorClass;
+      this.parameters = parameters;
+    }
+  }
+
+  private static native int roundTrip(Callback callback, boolean nested);
+
+  private static native void roundTripWithFailedCapture(Callback callback, 
Throwable failure);
+
+  private static native void roundTripOnWorker(
+      Callback callback, Callback nextCallback, Throwable captureFailure);
+
+  private static native int roundTripWithPendingException(
+      Callback callback, boolean nested, Throwable pending);
+
+  private static native int roundTripWithFailedRestore(
+      Callback callback, boolean nested, Throwable failure);
+
+  private static native void throwNativeException();
+
+  private static native void close();
+
+  private static native boolean entryActive();
+
+  @BeforeClass
+  public static void loadLibrary() {
+    String directory = System.getProperty("gluten.jni.test.lib.dir");
+    Assert.assertNotNull(
+        "Enable the jni-test Maven profile to configure the native bridge", 
directory);
+    System.load(
+        new File(directory, 
System.mapLibraryName("java_exception_jni_test")).getAbsolutePath());
+    libraryLoaded = true;
+  }
+
+  @AfterClass
+  public static void releaseReferences() {
+    if (libraryLoaded) {
+      close();
+    }
+  }
+
+  @Test
+  public void direct() {
+    preservesThrowable(false);
+  }
+
+  @Test
+  public void nested() {
+    preservesThrowable(true);
+  }
+
+  @Test
+  public void directRetainsAlreadyPendingException() {
+    retainsAlreadyPendingException(false);
+  }
+
+  @Test
+  public void nestedRetainsAlreadyPendingException() {
+    retainsAlreadyPendingException(true);
+  }
+
+  private static void retainsAlreadyPendingException(boolean nested) {
+    ArithmeticException original = new ArithmeticException("original callback 
failure");
+    IllegalStateException newer = new IllegalStateException("newer pending 
exception");
+    try {
+      roundTripWithPendingException(
+          () -> {
+            throw original;
+          },
+          nested,
+          newer);
+      Assert.fail("Expected the newer pending Java exception");
+    } catch (RuntimeException actual) {
+      Assert.assertSame(newer, actual);
+    }
+    preservesThrowable(nested);
+  }
+
+  @Test
+  public void failedDirectRestorationFallsBack() {
+    failedRestorationFallsBack(false);
+  }
+
+  @Test
+  public void failedNestedRestorationFallsBack() {
+    failedRestorationFallsBack(true);
+  }
+
+  private static void failedRestorationFallsBack(boolean nested) {
+    ArithmeticException original = new ArithmeticException("original callback 
failure");
+    try {
+      roundTripWithFailedRestore(
+          () -> {
+            throw original;
+          },
+          nested,
+          null);
+      Assert.fail("Failed restoration must not return without a Java 
exception");
+    } catch (GlutenException actual) {
+      Assert.assertSame(GlutenException.class, actual.getClass());
+      Assert.assertNull(actual.getCause());
+      if (nested) {
+        Assert.assertEquals("native wrapper", actual.getMessage());
+      } else {
+        Assert.assertTrue(actual.getMessage().contains("original callback 
failure"));
+      }
+    }
+    preservesThrowable(nested);
+  }
+
+  @Test
+  public void failedDirectRestorationRetainsPendingError() {
+    failedRestorationRetainsPendingError(false);
+  }
+
+  @Test
+  public void failedNestedRestorationRetainsPendingError() {
+    failedRestorationRetainsPendingError(true);
+  }
+
+  private static void failedRestorationRetainsPendingError(boolean nested) {
+    OutOfMemoryError newer = new OutOfMemoryError("injected restoration 
failure");
+    try {
+      roundTripWithFailedRestore(
+          () -> {
+            throw new ArithmeticException("original callback failure");
+          },
+          nested,
+          newer);
+      Assert.fail("Expected the newer pending Java exception");
+    } catch (OutOfMemoryError actual) {
+      Assert.assertSame(newer, actual);
+    }
+    preservesThrowable(nested);
+  }
+
+  private static void preservesThrowable(boolean nested) {
+    preservesThrowable(callback -> roundTrip(callback, nested));
+  }
+
+  private static void preservesThrowable(Consumer<Callback> invoke) {
+    StructuredException original =
+        new StructuredException("TEST_ERROR", 
Collections.singletonMap("value", "original"));
+    Throwable cause = new IllegalStateException("original cause");
+    Throwable suppressed = new IllegalArgumentException("original suppressed 
exception");
+    original.initCause(cause);
+    original.addSuppressed(suppressed);
+    StackTraceElement[] stack = original.getStackTrace();
+    try {
+      invoke.accept(
+          () -> {
+            throw original;
+          });
+      Assert.fail("Expected the original exception");
+    } catch (StructuredException actual) {
+      Assert.assertSame(original, actual);
+      Assert.assertSame(original.getClass(), actual.getClass());
+      Assert.assertSame(cause, actual.getCause());
+      Assert.assertEquals(1, actual.getSuppressed().length);
+      Assert.assertSame(suppressed, actual.getSuppressed()[0]);
+      Assert.assertArrayEquals(stack, actual.getStackTrace());
+      Assert.assertEquals("TEST_ERROR", actual.errorClass);
+      Assert.assertEquals(Collections.singletonMap("value", "original"), 
actual.parameters);
+    }
+  }
+
+  @Test
+  public void failedCaptureRetainsPendingErrorAtJavaEntry() {
+    OutOfMemoryError newer = new OutOfMemoryError("injected global reference 
failure");
+    try {
+      roundTripWithFailedCapture(
+          () -> {
+            throw new ArithmeticException("original callback failure");
+          },
+          newer);
+      Assert.fail("Expected the newer pending error at the Java return 
boundary");
+    } catch (OutOfMemoryError actual) {
+      Assert.assertSame(newer, actual);
+    }
+  }
+
+  @Test
+  public void failedCaptureDoesNotPoisonReusedWorker() {
+    AtomicReference<Thread> worker = new AtomicReference<>();
+    int[] calls = {0};
+    try {
+      roundTripOnWorker(
+          () -> {
+            worker.set(Thread.currentThread());
+            throw new ArithmeticException("original worker failure");
+          },
+          () -> {
+            Assert.assertSame(worker.get(), Thread.currentThread());
+            calls[0]++;
+          },
+          new OutOfMemoryError("injected global reference failure"));
+      Assert.fail("Expected the native capture failure");
+    } catch (GlutenException actual) {
+      Assert.assertEquals(
+          "Unable to create global reference for Java exception", 
actual.getMessage());
+    }
+    Assert.assertEquals(1, calls[0]);
+    Assert.assertNotSame(Thread.currentThread(), worker.get());
+  }
+
+  @Test
+  public void capturedWorkerThrowableSurvivesReuse() {
+    AtomicReference<Thread> worker = new AtomicReference<>();
+    int[] calls = {0};
+    preservesThrowable(
+        callback ->
+            roundTripOnWorker(
+                () -> {
+                  worker.set(Thread.currentThread());
+                  callback.run();
+                },
+                () -> {
+                  Assert.assertSame(worker.get(), Thread.currentThread());
+                  calls[0]++;
+                },
+                null));
+    Assert.assertEquals(1, calls[0]);
+    Assert.assertNotSame(Thread.currentThread(), worker.get());
+  }
+
+  @Test
+  public void nestedJavaReentryRestoresScope() {
+    Assert.assertFalse(entryActive());
+    roundTrip(
+        () -> {
+          Assert.assertTrue(entryActive());
+          normalReturn();
+          Assert.assertTrue(entryActive());
+          nativeOnly();
+          Assert.assertTrue(entryActive());
+          failedCaptureRetainsPendingErrorAtJavaEntry();
+          Assert.assertTrue(entryActive());
+        },
+        false);
+    Assert.assertFalse(entryActive());
+    preservesThrowable(false);
+    Assert.assertFalse(entryActive());
+  }
+
+  @Test
+  public void nativeOnly() {
+    try {
+      throwNativeException();
+      Assert.fail("Expected GlutenException");
+    } catch (GlutenException actual) {
+      Assert.assertSame(GlutenException.class, actual.getClass());
+      Assert.assertNull(actual.getCause());
+      Assert.assertEquals("native-only failure", actual.getMessage());
+    }
+  }
+
+  @Test
+  public void normalReturn() {
+    for (boolean nested : new boolean[] {false, true}) {
+      int[] calls = {0};
+      int result = roundTrip(() -> calls[0]++, nested);
+      Assert.assertEquals(42, result);
+      Assert.assertEquals(1, calls[0]);
+    }
+  }
+}


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

Reply via email to