From 468ba2bb33103969b03a986eaecac57d23df2cb2 Mon Sep 17 00:00:00 2001 From: Nelson Osacky Date: Wed, 18 Nov 2026 12:34:36 +0100 Subject: [PATCH] docs(core): Document how scope callbacks handle exceptions Scopes keeps swallowing the non-fatal exceptions of the withScope, withIsolationScope and configureScope callbacks, and rethrows fatal errors since the first PR in this stack. Document that on IScopes and the Sentry static methods, including that the failure only shows up in the debug log, and that before init the callback either runs on a no-op scope without a catch or doesn't run at all. Test both outcomes through Scopes, Sentry and ScopesAdapter. Refs JAVA-552 Co-Authored-By: Claude Opus 5.5 --- sentry/src/main/java/io/sentry/IScopes.java | 22 ++++++ sentry/src/main/java/io/sentry/Sentry.java | 22 ++++++ sentry/src/test/java/io/sentry/ScopesTest.kt | 73 ++++++++++++++++++++ sentry/src/test/java/io/sentry/SentryTest.kt | 27 ++++++++ 4 files changed, 144 insertions(+) diff --git a/sentry/src/main/java/io/sentry/IScopes.java b/sentry/src/main/java/io/sentry/IScopes.java index 6b5a2b8a5b7..c1ffa4f7d69 100644 --- a/sentry/src/main/java/io/sentry/IScopes.java +++ b/sentry/src/main/java/io/sentry/IScopes.java @@ -351,6 +351,12 @@ default void addBreadcrumb(@NotNull String message, @NotNull String category) { * changes may be dropped when executed in parallel. Use {@link * IScopes#configureScope(ScopeCallback)} instead. * + *

If the callback throws, the rest of it is skipped and the exception is logged at {@link + * SentryLevel#ERROR} through {@link SentryOptions#getLogger()}, which by default prints only when + * {@link SentryOptions#isDebug()} is enabled. Fatal errors, such as {@link OutOfMemoryError}, are + * rethrown. Before {@link Sentry#init}, the callback runs on a no-op scope and nothing it throws + * is caught. + * * @param callback the callback */ void withScope(@NotNull ScopeCallback callback); @@ -364,6 +370,12 @@ default void addBreadcrumb(@NotNull String message, @NotNull String category) { * changes may be dropped when executed in parallel. Use {@link IScopes#configureScope(ScopeType, * ScopeCallback)} instead. * + *

If the callback throws, the rest of it is skipped and the exception is logged at {@link + * SentryLevel#ERROR} through {@link SentryOptions#getLogger()}, which by default prints only when + * {@link SentryOptions#isDebug()} is enabled. Fatal errors, such as {@link OutOfMemoryError}, are + * rethrown. Before {@link Sentry#init}, the callback runs on a no-op scope and nothing it throws + * is caught. + * * @param callback the callback */ void withIsolationScope(@NotNull ScopeCallback callback); @@ -371,6 +383,11 @@ default void addBreadcrumb(@NotNull String message, @NotNull String category) { /** * Configures the scope through the callback. * + *

If the callback throws, the rest of it is skipped and the exception is logged at {@link + * SentryLevel#ERROR} through {@link SentryOptions#getLogger()}, which by default prints only when + * {@link SentryOptions#isDebug()} is enabled. Fatal errors, such as {@link OutOfMemoryError}, are + * rethrown. Before {@link Sentry#init}, the callback isn't run. + * * @param callback The configure scope callback. */ default void configureScope(@NotNull ScopeCallback callback) { @@ -380,6 +397,11 @@ default void configureScope(@NotNull ScopeCallback callback) { /** * Configures the scope through the callback. * + *

If the callback throws, the rest of it is skipped and the exception is logged at {@link + * SentryLevel#ERROR} through {@link SentryOptions#getLogger()}, which by default prints only when + * {@link SentryOptions#isDebug()} is enabled. Fatal errors, such as {@link OutOfMemoryError}, are + * rethrown. Before {@link Sentry#init}, the callback isn't run. + * * @param callback The configure scope callback. */ void configureScope(@Nullable ScopeType scopeType, @NotNull ScopeCallback callback); diff --git a/sentry/src/main/java/io/sentry/Sentry.java b/sentry/src/main/java/io/sentry/Sentry.java index b769b50ddbd..bec5ae5d42c 100644 --- a/sentry/src/main/java/io/sentry/Sentry.java +++ b/sentry/src/main/java/io/sentry/Sentry.java @@ -1050,6 +1050,12 @@ public static void removeExtra(final @Nullable String key) { *

Unlike {@link Sentry#pushScope()} this also forks in global hub mode, since the previous * scopes are always restored once the callback returns. * + *

If the callback throws, the rest of it is skipped and the exception is logged at {@link + * SentryLevel#ERROR} through {@link SentryOptions#getLogger()}, which by default prints only when + * {@link SentryOptions#isDebug()} is enabled. Fatal errors, such as {@link OutOfMemoryError}, are + * rethrown. Before {@link #init} and after {@link #close}, the callback runs on a no-op scope and + * nothing it throws is caught. + * * @param callback the callback */ public static void withScope(final @NotNull ScopeCallback callback) { @@ -1063,6 +1069,12 @@ public static void withScope(final @NotNull ScopeCallback callback) { *

Unlike {@link Sentry#pushIsolationScope()} this also forks in global hub mode, since the * previous scopes are always restored once the callback returns. * + *

If the callback throws, the rest of it is skipped and the exception is logged at {@link + * SentryLevel#ERROR} through {@link SentryOptions#getLogger()}, which by default prints only when + * {@link SentryOptions#isDebug()} is enabled. Fatal errors, such as {@link OutOfMemoryError}, are + * rethrown. Before {@link #init} and after {@link #close}, the callback runs on a no-op scope and + * nothing it throws is caught. + * * @param callback the callback */ public static void withIsolationScope(final @NotNull ScopeCallback callback) { @@ -1072,6 +1084,11 @@ public static void withIsolationScope(final @NotNull ScopeCallback callback) { /** * Configures the scope through the callback. * + *

If the callback throws, the rest of it is skipped and the exception is logged at {@link + * SentryLevel#ERROR} through {@link SentryOptions#getLogger()}, which by default prints only when + * {@link SentryOptions#isDebug()} is enabled. Fatal errors, such as {@link OutOfMemoryError}, are + * rethrown. Before {@link #init} and after {@link #close}, the callback isn't run. + * * @param callback The configure scope callback. */ public static void configureScope(final @NotNull ScopeCallback callback) { @@ -1081,6 +1098,11 @@ public static void configureScope(final @NotNull ScopeCallback callback) { /** * Configures the scope through the callback. * + *

If the callback throws, the rest of it is skipped and the exception is logged at {@link + * SentryLevel#ERROR} through {@link SentryOptions#getLogger()}, which by default prints only when + * {@link SentryOptions#isDebug()} is enabled. Fatal errors, such as {@link OutOfMemoryError}, are + * rethrown. Before {@link #init} and after {@link #close}, the callback isn't run. + * * @param callback The configure scope callback. */ public static void configureScope( diff --git a/sentry/src/test/java/io/sentry/ScopesTest.kt b/sentry/src/test/java/io/sentry/ScopesTest.kt index acd2b764ada..1bf1f6529fe 100644 --- a/sentry/src/test/java/io/sentry/ScopesTest.kt +++ b/sentry/src/test/java/io/sentry/ScopesTest.kt @@ -956,6 +956,31 @@ class ScopesTest { verify(logger).log(eq(SentryLevel.ERROR), any(), eq(exception)) } + @Test + fun `when withScope throws a runtime exception then it is swallowed`() { + val (scopes, _, logger) = getEnabledScopes() + val exception = IllegalStateException("scope callback exception") + + scopes.withScope { throw exception } + + verify(logger).log(eq(SentryLevel.ERROR), any(), eq(exception)) + } + + @Test + fun `when withScope throws a fatal error then it propagates`() { + val (scopes) = getEnabledScopes() + + assertFailsWith { scopes.withScope { throw OutOfMemoryError("callback") } } + } + + @Test + fun `when withScope on a closed scopes throws a fatal error then it propagates`() { + val (scopes) = getEnabledScopes() + scopes.close() + + assertFailsWith { scopes.withScope { throw OutOfMemoryError("callback") } } + } + // endregion // region withIsolationScope tests @@ -992,6 +1017,35 @@ class ScopesTest { verify(logger).log(eq(SentryLevel.ERROR), any(), eq(exception)) } + @Test + fun `when withIsolationScope throws a runtime exception then it is swallowed`() { + val (scopes, _, logger) = getEnabledScopes() + val exception = IllegalStateException("scope callback exception") + + scopes.withIsolationScope { throw exception } + + verify(logger).log(eq(SentryLevel.ERROR), any(), eq(exception)) + } + + @Test + fun `when withIsolationScope throws a fatal error then it propagates`() { + val (scopes) = getEnabledScopes() + + assertFailsWith { + scopes.withIsolationScope { throw OutOfMemoryError("callback") } + } + } + + @Test + fun `when withIsolationScope on a closed scopes throws a fatal error then it propagates`() { + val (scopes) = getEnabledScopes() + scopes.close() + + assertFailsWith { + scopes.withIsolationScope { throw OutOfMemoryError("callback") } + } + } + // endregion // region configureScope tests @@ -1028,6 +1082,25 @@ class ScopesTest { verify(logger).log(eq(SentryLevel.ERROR), any(), eq(exception)) } + @Test + fun `when configureScope throws a runtime exception then it is swallowed`() { + val (scopes, _, logger) = getEnabledScopes() + val exception = IllegalStateException("scope callback exception") + + scopes.configureScope { throw exception } + + verify(logger).log(eq(SentryLevel.ERROR), any(), eq(exception)) + } + + @Test + fun `when configureScope throws a fatal error then it propagates`() { + val (scopes) = getEnabledScopes() + + assertFailsWith { + scopes.configureScope { throw OutOfMemoryError("callback") } + } + } + // endregion @Test diff --git a/sentry/src/test/java/io/sentry/SentryTest.kt b/sentry/src/test/java/io/sentry/SentryTest.kt index 3ceac1ffdaa..78cbbdf7dc8 100644 --- a/sentry/src/test/java/io/sentry/SentryTest.kt +++ b/sentry/src/test/java/io/sentry/SentryTest.kt @@ -39,6 +39,7 @@ import kotlin.test.BeforeTest import kotlin.test.Test import kotlin.test.assertEquals import kotlin.test.assertFails +import kotlin.test.assertFailsWith import kotlin.test.assertFalse import kotlin.test.assertIs import kotlin.test.assertNotEquals @@ -1561,6 +1562,32 @@ class SentryTest { } } + @Test + fun `scope callbacks that throw a runtime exception are swallowed`() { + initForTest { o -> o.dsn = dsn } + + Sentry.withScope { throw IllegalStateException("withScope") } + Sentry.withIsolationScope { throw IllegalStateException("withIsolationScope") } + Sentry.configureScope { throw IllegalStateException("configureScope") } + ScopesAdapter.getInstance().withScope { throw IllegalStateException("adapter withScope") } + } + + @Test + fun `scope callbacks that throw a fatal error propagate`() { + initForTest { o -> o.dsn = dsn } + + assertFailsWith { Sentry.withScope { throw OutOfMemoryError("withScope") } } + assertFailsWith { + Sentry.withIsolationScope { throw OutOfMemoryError("withIsolationScope") } + } + assertFailsWith { + Sentry.configureScope { throw OutOfMemoryError("configureScope") } + } + assertFailsWith { + ScopesAdapter.getInstance().configureScope { throw OutOfMemoryError("adapter") } + } + } + @Test fun `withScope data does not leak into events captured after the callback`() { for (globalHubMode in listOf(false, true)) {