feat(ndk): expose init return code (#1430)

hannojg · markushi · supervacuus · web-flow · commit b57211c39e92 · 2026-02-18T14:33:09.000+01:00
* ndk: expose init return code from sentry_init

* changelog: note SentryNdk.init return code

* formatting

* Address PR feedback

* fix up CHANGELOG.md

* release ready fixup

---------

Co-authored-by: Markus Hintersteiner &lt;markus.hintersteiner@sentry.io&gt;
Co-authored-by: Mischan Toosarani-Hausberger &lt;mischan@abovevacant.com&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,26 +1,18 @@
 # Changelog
 
-## 0.12.8
-
-**Fixes**:
-
-- Fix deadlock when re-initializing the SDK while logs or metrics threads are mid-flush. ([#1518](https://github.com/getsentry/sentry-native/pull/1518))
-
-## 0.12.7
+## Unreleased
 
 **Breaking**:
 
 - inproc: since we split `inproc` into signal-handler/UEF part and a separate handler thread, `before_send` and `on_crash` could be called from other threads than the one that crashed. While this was never part of the contract, if your code relies on this, it will no longer work. ([#1446](https://github.com/getsentry/sentry-native/pull/1446))
+- Android NDK: `SentryNdk.init(NdkOptions)` now throws an `Exception` if init fails (non-zero return code) rather than silently swallowing the error. ([#1430](https://github.com/getsentry/sentry-native/pull/1430))
 
 **Features**:
 
-- Add new offline caching options to persist envelopes locally: `sentry_options_set_cache_keep`, `sentry_options_set_cache_max_items`, `sentry_options_set_cache_max_size`, and `sentry_options_set_cache_max_age`. ([#1490](https://github.com/getsentry/sentry-native/pull/1490), [#1493](https://github.com/getsentry/sentry-native/pull/1493))
-- Add support for `abort()` in the `inproc` backend on Windows. ([#1446](https://github.com/getsentry/sentry-native/pull/1446)) 
+- Add support for `abort()` in the `inproc` backend on Windows. ([#1446](https://github.com/getsentry/sentry-native/pull/1446))
 
 **Fixes**:
 
-- Remove spurious decref in `sentry_capture_user_feedback()` ([#1510](https://github.com/getsentry/sentry-native/pull/1510))
-- Prevent double-decref of event in envelope add functions ([#1511](https://github.com/getsentry/sentry-native/pull/1511))
 - Make the signal-handler synchronization fully atomic to fix rare race scenarios. ([#1446](https://github.com/getsentry/sentry-native/pull/1446))
 - Reintroduce an FP-based stack-walker for macOS that can start from a user context. This also makes `inproc` backend functional again on macOS 13+. ([#1446](https://github.com/getsentry/sentry-native/pull/1446))
 - Split the `inproc` signal handler (and UEF on Windows) into a safe handler part and an "unsafe" handler thread. This minimizes exposure to undefined behavior inside the signal handler. ([#1446](https://github.com/getsentry/sentry-native/pull/1446))
@@ -31,6 +23,27 @@
 - Introduce PAC tests for `arm64e` on macOS. ([#1446](https://github.com/getsentry/sentry-native/pull/1446))
 - For Linux, the SDK now has a vendored "nognu" `libunwind` as the default stack walker and links it statically, but with PIC enabled so it can be used in PIE executables. ([#1446](https://github.com/getsentry/sentry-native/pull/1446))
 
+**Thank you**:
+
+- [hannojg](https://github.com/hannojg)
+
+## 0.12.8
+
+**Fixes**:
+
+- Fix deadlock when re-initializing the SDK while logs or metrics threads are mid-flush. ([#1518](https://github.com/getsentry/sentry-native/pull/1518))
+
+## 0.12.7
+
+**Features**:
+
+- Add new offline caching options to persist envelopes locally: `sentry_options_set_cache_keep`, `sentry_options_set_cache_max_items`, `sentry_options_set_cache_max_size`, and `sentry_options_set_cache_max_age`. ([#1490](https://github.com/getsentry/sentry-native/pull/1490), [#1493](https://github.com/getsentry/sentry-native/pull/1493))
+
+**Fixes**:
+
+- Remove spurious decref in `sentry_capture_user_feedback()` ([#1510](https://github.com/getsentry/sentry-native/pull/1510))
+- Prevent double-decref of event in envelope add functions ([#1511](https://github.com/getsentry/sentry-native/pull/1511))
+
 ## 0.12.6
 
 **Features**:
diff --git a/ndk/lib/src/androidTest/java/io/sentry/ndk/SentryNdkTest.java b/ndk/lib/src/androidTest/java/io/sentry/ndk/SentryNdkTest.java
@@ -65,6 +65,30 @@ public void shutdownDoesNotFail() throws IOException {
     // it does not crash
   }
 
+  @Test(expected = IllegalStateException.class)
+  public void initThrowsException() throws IOException {
+    final TemporaryFolder temporaryFolder = TemporaryFolder.builder().build();
+    temporaryFolder.create();
+    final File outboxPath = temporaryFolder.newFolder("outboxPath");
+
+    //noinspection DataFlowIssue
+    final NdkOptions options =
+        new NdkOptions(
+            null,
+            true,
+            outboxPath.getAbsolutePath(),
+            "1.0.0",
+            "production",
+            "dist",
+            100,
+            "io.sentry.ndk");
+
+    // when initialized with a NULL dsn
+    SentryNdk.init(options);
+
+    // then it does crash
+  }
+
   @Test
   public void messageCaught() throws IOException {
     final TemporaryFolder temporaryFolder = TemporaryFolder.builder().build();
diff --git a/ndk/lib/src/main/java/io/sentry/ndk/SentryNdk.java b/ndk/lib/src/main/java/io/sentry/ndk/SentryNdk.java
@@ -10,18 +10,31 @@ public final class SentryNdk {
 
   private SentryNdk() {}
 
-  private static native void initSentryNative(@NotNull final NdkOptions options);
+  /**
+   * Initializes sentry-native and returns 0 on success, non-zero on failure.
+   *
+   * @return -1 if an JNI or options configuration issue occurred, 1 if sentry native itself failed
+   *     to initialize
+   */
+  private static native int initSentryNative(@NotNull final NdkOptions options);
 
   private static native void shutdown();
 
   /**
    * Init the NDK integration
    *
    * @param options the SentryAndroidOptions
+   * @throws IllegalStateException if sentry-native couldn't be initialized
    */
   public static void init(@NotNull final NdkOptions options) {
     loadNativeLibraries();
-    initSentryNative(options);
+    final int returnCode = initSentryNative(options);
+    if (returnCode > 0) {
+      throw new IllegalStateException(
+          "A sentry-native internal init error occurred, please check the logs for more details.");
+    } else if (returnCode < 0) {
+      throw new IllegalStateException("A sentry-native setup failure occurred");
+    }
   }
 
   /** Closes the NDK integration */
diff --git a/ndk/lib/src/main/jni/sentry.c b/ndk/lib/src/main/jni/sentry.c
@@ -247,7 +247,7 @@ static void send_envelope(sentry_envelope_t *envelope, void *data) {
     sentry_envelope_free(envelope);
 }
 
-JNIEXPORT void JNICALL
+JNIEXPORT jint JNICALL
 Java_io_sentry_ndk_SentryNdk_initSentryNative(
         JNIEnv *env,
         jclass cls,
@@ -355,8 +355,8 @@ Java_io_sentry_ndk_SentryNdk_initSentryNative(
     jfloat traces_sample_rate = (jfloat) (*env)->CallFloatMethod(env, sentry_ndk_options, traces_sample_rate_mid);
     sentry_options_set_traces_sample_rate(options, traces_sample_rate);
 
-    sentry_init(options);
-    return;
+    int rv = sentry_init(options);
+    return (jint) rv;
 
     fail:
     if (!transport_owns_path) {
@@ -366,6 +366,7 @@ Java_io_sentry_ndk_SentryNdk_initSentryNative(
         sentry_transport_free(transport);
     }
     sentry_options_free(options);
+    return (jint) -1;
 }
 
 JNIEXPORT void JNICALL
