Merge pull request #2384 from bugsnag/PLAT-15492/improve-oom-reporting

New OOM Handling Options

Author: lemnik

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## TBD
+
+### Enhancements
+
+* Added `NativeOutOfMemoryPlugin` as a new way to report `OutOfMemoryError`s that uses pre-allocated memory in the NDK module instead of allocating an `Event` object. When used `OutOfMemoryError`s will be more reliably reported, but will not be passed to `OnErrorCallback`s (`OnSendCallback` works as expected).
+  [#2384](https://github.com/bugsnag/bugsnag-android/pull/2384)
+
 ## 6.24.0 (2026-02-11)
 
 ### Enhancements

bugsnag-android-core/api/bugsnag-android-core.api

@@ -88,6 +88,7 @@ public final class com/bugsnag/android/Bugsnag {
 	public static fun getLastRunInfo ()Lcom/bugsnag/android/LastRunInfo;
 	public static fun getMetadata (Ljava/lang/String;)Ljava/util/Map;
 	public static fun getMetadata (Ljava/lang/String;Ljava/lang/String;)Ljava/lang/Object;
+	public static fun getOutOfMemoryHandler ()Lcom/bugsnag/android/OutOfMemoryHandler;
 	public static fun getUser ()Lcom/bugsnag/android/User;
 	public static fun isStarted ()Z
 	public static fun leaveBreadcrumb (Ljava/lang/String;)V
@@ -103,6 +104,7 @@ public final class com/bugsnag/android/Bugsnag {
 	public static fun resumeSession ()Z
 	public static fun setContext (Ljava/lang/String;)V
 	public static fun setGroupingDiscriminator (Ljava/lang/String;)Ljava/lang/String;
+	public static fun setOutOfMemoryHandler (Lcom/bugsnag/android/OutOfMemoryHandler;)V
 	public static fun setUser (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;)V
 	public static fun start (Landroid/content/Context;)Lcom/bugsnag/android/Client;
 	public static fun start (Landroid/content/Context;Lcom/bugsnag/android/Configuration;)Lcom/bugsnag/android/Client;
@@ -147,6 +149,7 @@ public class com/bugsnag/android/Client : com/bugsnag/android/CallbackAware, com
 	public fun getLastRunInfo ()Lcom/bugsnag/android/LastRunInfo;
 	public fun getMetadata (Ljava/lang/String;)Ljava/util/Map;
 	public fun getMetadata (Ljava/lang/String;Ljava/lang/String;)Ljava/lang/Object;
+	public fun getOutOfMemoryHandler ()Lcom/bugsnag/android/OutOfMemoryHandler;
 	public fun getUser ()Lcom/bugsnag/android/User;
 	public fun leaveBreadcrumb (Ljava/lang/String;)V
 	public fun leaveBreadcrumb (Ljava/lang/String;Ljava/util/Map;Lcom/bugsnag/android/BreadcrumbType;)V
@@ -161,6 +164,7 @@ public class com/bugsnag/android/Client : com/bugsnag/android/CallbackAware, com
 	public fun resumeSession ()Z
 	public fun setContext (Ljava/lang/String;)V
 	public fun setGroupingDiscriminator (Ljava/lang/String;)Ljava/lang/String;
+	public fun setOutOfMemoryHandler (Lcom/bugsnag/android/OutOfMemoryHandler;)V
 	public fun setUser (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;)V
 	public fun startSession ()V
 }
@@ -700,6 +704,10 @@ public abstract interface class com/bugsnag/android/OnSessionCallback {
 	public abstract fun onSession (Lcom/bugsnag/android/Session;)Z
 }
 
+public abstract interface class com/bugsnag/android/OutOfMemoryHandler {
+	public abstract fun onOutOfMemory (Ljava/lang/OutOfMemoryError;)Z
+}
+
 public abstract interface class com/bugsnag/android/Plugin {
 	public abstract fun load (Lcom/bugsnag/android/Client;)V
 	public abstract fun unload ()V

bugsnag-android-core/src/main/java/com/bugsnag/android/Bugsnag.java

@@ -498,6 +498,26 @@ public static void clearFeatureFlags() {
         getClient().clearFeatureFlags();
     }
 
+    /**
+     * Override or intercept the default error handling for {@link OutOfMemoryError}s.
+     *
+     * @param handler the new handler to use (or null to revert to normal error handling for OOMs)
+     * @see #getOutOfMemoryHandler()
+     */
+    public static void setOutOfMemoryHandler(@Nullable OutOfMemoryHandler handler) {
+        getClient().setOutOfMemoryHandler(handler);
+    }
+
+    /**
+     * Return the currently defined {@link OutOfMemoryHandler} if one is being used.
+     *
+     * @return the current {@code OutOfMemoryHandler} or null if none is set
+     */
+    @Nullable
+    public static OutOfMemoryHandler getOutOfMemoryHandler() {
+        return getClient().getOutOfMemoryHandler();
+    }
+
     /**
      * Get the current Bugsnag Client instance.
      */

bugsnag-android-core/src/main/java/com/bugsnag/android/Client.java

@@ -938,6 +938,31 @@ void notifyInternalWithErrorOptions(@NonNull Event event,
         }
     }
 
+    /**
+     * Override or intercept the default error handling for {@link OutOfMemoryError}s.
+     *
+     * @param handler the new handler to use (or null to revert to normal error handling for OOMs)
+     * @see #getOutOfMemoryHandler()
+     */
+    public void setOutOfMemoryHandler(@Nullable OutOfMemoryHandler handler) {
+        if (exceptionHandler != null) {
+            exceptionHandler.setOutOfMemoryHandler(handler);
+        }
+    }
+
+    /**
+     * Return the currently defined {@link OutOfMemoryHandler} if one is being used.
+     *
+     * @return the current {@code OutOfMemoryHandler} or null if none is set
+     */
+    @Nullable
+    public OutOfMemoryHandler getOutOfMemoryHandler() {
+        if (exceptionHandler == null) {
+            return null;
+        }
+        return exceptionHandler.getOutOfMemoryHandler();
+    }
+
     /**
      * Returns the current buffer of breadcrumbs that will be sent with captured events. This
      * ordered list represents the most recent breadcrumbs to be captured up to the limit

bugsnag-android-core/src/main/java/com/bugsnag/android/ExceptionHandler.java

@@ -21,6 +21,8 @@ class ExceptionHandler implements UncaughtExceptionHandler {
     private final Logger logger;
     private boolean enabled = true;
 
+    private OutOfMemoryHandler outOfMemoryHandler = null;
+
     ExceptionHandler(Client client, Logger logger) {
         this.client = client;
         this.logger = logger;
@@ -37,13 +39,26 @@ void uninstall() {
         Thread.setDefaultUncaughtExceptionHandler(originalHandler);
     }
 
+    public void setOutOfMemoryHandler(OutOfMemoryHandler outOfMemoryHandler) {
+        this.outOfMemoryHandler = outOfMemoryHandler;
+    }
+
+    public OutOfMemoryHandler getOutOfMemoryHandler() {
+        return outOfMemoryHandler;
+    }
+
     @Override
     public void uncaughtException(@NonNull Thread thread, @NonNull Throwable throwable) {
         try {
             if (!enabled || client.getConfig().shouldDiscardError(throwable)) {
                 return;
             }
 
+            if (throwable instanceof OutOfMemoryError
+                    && tryHandleOutOfMemory((OutOfMemoryError) throwable)) {
+                return;
+            }
+
             boolean strictModeThrowable = strictModeHandler.isStrictModeThrowable(throwable);
 
             // Notify any subscribed clients of the uncaught exception
@@ -88,4 +103,13 @@ private void forwardToOriginalHandler(@NonNull Thread thread, @NonNull Throwable
             logger.w("Exception", throwable);
         }
     }
+
+    private boolean tryHandleOutOfMemory(OutOfMemoryError oom) {
+        OutOfMemoryHandler handler = outOfMemoryHandler;
+        if (handler == null) {
+            return false;
+        }
+
+        return handler.onOutOfMemory(oom);
+    }
 }

bugsnag-android-core/src/main/java/com/bugsnag/android/OutOfMemoryHandler.kt

@@ -0,0 +1,14 @@
+package com.bugsnag.android
+
+fun interface OutOfMemoryHandler {
+    /**
+     * Called when an `OutOfMemoryError` is reported but before it is handled by Bugsnag. This
+     * can be used to either fully-process the `OutOfMemoryError` on a safe path, or can
+     * attempt to free more memory to allow the `OutOfMemoryError` error to be processed and
+     * reported (as a normal [Event]).
+     *
+     * @return true if the `OutOfMemoryError` was fully reported by this handler, `false` if normal
+     *  error reporting should continue
+     */
+    fun onOutOfMemory(oom: OutOfMemoryError): Boolean
+}

bugsnag-android-core/src/main/java/com/bugsnag/android/ThrowableExtensions.kt

@@ -1,6 +1,11 @@
 @file:JvmName("ThrowableUtils")
 package com.bugsnag.android
 
+/**
+ * The maximum number of causes to consider when unrolling the cause chain for a Throwable.
+ */
+private const val MAX_CAUSE_COUNT = 100
+
 /**
  * Unroll the list of causes for this Throwable, handling any recursion that may appear within
  * the chain. The first element returned will be this Throwable, and the last will be the root
@@ -17,3 +22,30 @@ internal fun Throwable.safeUnrollCauses(): List<Throwable> {
 
     return causes.toList()
 }
+
+internal inline fun Throwable.anyCauseMatches(action: (Throwable) -> Boolean): Boolean {
+    var current: Throwable? = this
+    var slow: Throwable? = this
+    var advanceSlow = false
+    var depth = 0
+
+    while (current != null && depth < MAX_CAUSE_COUNT) {
+        if (action(current)) {
+            return true
+        }
+
+        current = current.cause
+
+        // Floyd's cycle detection (no allocation required)
+        if (advanceSlow) {
+            slow = slow?.cause
+            if (current === slow) {
+                return false
+            }
+        }
+        advanceSlow = !advanceSlow
+        depth++
+    }
+
+    return false
+}

bugsnag-android-core/src/main/java/com/bugsnag/android/internal/ImmutableConfig.kt

@@ -21,10 +21,10 @@ import com.bugsnag.android.NoopLogger
 import com.bugsnag.android.Session
 import com.bugsnag.android.Telemetry
 import com.bugsnag.android.ThreadSendPolicy
+import com.bugsnag.android.anyCauseMatches
 import com.bugsnag.android.errorApiHeaders
 import com.bugsnag.android.internal.dag.Provider
 import com.bugsnag.android.internal.dag.ValueProvider
-import com.bugsnag.android.safeUnrollCauses
 import com.bugsnag.android.sessionApiHeaders
 import java.io.File
 import java.util.regex.Pattern
@@ -132,7 +132,7 @@ data class ImmutableConfig(
      */
     @VisibleForTesting
     internal fun shouldDiscardByErrorClass(exc: Throwable): Boolean {
-        return exc.safeUnrollCauses().any { throwable ->
+        return exc.anyCauseMatches { throwable ->
             val errorClass = throwable.javaClass.name
             shouldDiscardByErrorClass(errorClass)
         }

bugsnag-android-core/src/test/java/com/bugsnag/android/ThrowableCauseMatchingTest.kt

@@ -0,0 +1,49 @@
+package com.bugsnag.android
+
+import android.os.RemoteException
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import java.io.IOException
+import java.util.concurrent.ExecutionException
+
+class ThrowableCauseMatchingTest {
+    @Test
+    fun matchSingle() {
+        val root = RuntimeException()
+        assertTrue(root.anyCauseMatches { it is RuntimeException })
+        assertFalse(root.anyCauseMatches { it is RemoteException })
+    }
+
+    @Test
+    fun simpleChain() {
+        val root = IOException()
+        val wrapper1 = RuntimeException(root)
+        val wrapper2 = ExecutionException(wrapper1)
+
+        assertTrue(wrapper2.anyCauseMatches { it is IOException })
+        assertTrue(wrapper2.anyCauseMatches { it is RuntimeException })
+        assertTrue(wrapper2.anyCauseMatches { it is ExecutionException })
+        assertFalse(wrapper2.anyCauseMatches { it is RemoteException })
+    }
+
+    @Test
+    fun complexRecursiveChain() {
+        val root = IOException("Root cause")
+        val wrapper1 = RuntimeException("Wrapper 1", root)
+        val wrapper2 = ExecutionException("Wrapper 2", wrapper1)
+        val wrapper3 = IllegalStateException("Wrapper 3", wrapper2)
+        val wrapper4 = IllegalArgumentException("Wrapper 4")
+        wrapper4.initCause(wrapper3)
+
+        // Create circular reference: root points back to wrapper4
+        root.initCause(wrapper4)
+
+        assertTrue(wrapper4.anyCauseMatches { it is IOException })
+        assertTrue(wrapper4.anyCauseMatches { it is RuntimeException })
+        assertTrue(wrapper4.anyCauseMatches { it is ExecutionException })
+        assertTrue(wrapper4.anyCauseMatches { it is IllegalStateException })
+        assertTrue(wrapper4.anyCauseMatches { it is IllegalArgumentException })
+        assertFalse(wrapper4.anyCauseMatches { it is RemoteException })
+    }
+}

bugsnag-plugin-android-ndk/api/bugsnag-plugin-android-ndk.api

@@ -1,3 +1,10 @@
+public final class com/bugsnag/android/NativeOutOfMemoryPlugin : com/bugsnag/android/OutOfMemoryHandler, com/bugsnag/android/Plugin {
+	public fun <init> ()V
+	public fun load (Lcom/bugsnag/android/Client;)V
+	public fun onOutOfMemory (Ljava/lang/OutOfMemoryError;)Z
+	public fun unload ()V
+}
+
 public final class com/bugsnag/android/ndk/BugsnagNDK {
 	public static final field INSTANCE Lcom/bugsnag/android/ndk/BugsnagNDK;
 	public static final fun refreshSymbolTable ()V
@@ -27,6 +34,7 @@ public final class com/bugsnag/android/ndk/NativeBridge : com/bugsnag/android/in
 	public final fun pausedSession ()V
 	public final fun refreshSymbolTable ()V
 	public final fun removeMetadata (Ljava/lang/String;Ljava/lang/String;)V
+	public final fun reportOutOfMemory (Ljava/lang/OutOfMemoryError;)V
 	public final fun setInternalMetricsEnabled (Z)V
 	public final fun setStaticJsonData (Ljava/lang/String;)V
 	public final fun startedSession (Ljava/lang/String;Ljava/lang/String;II)V