Skip to content

docs(core): [Throwable Boundaries 5] Document how scope callbacks handle exceptions - #6661

Closed
runningcode wants to merge 1 commit into
no/java-552-boundaries-jvmfrom
no/java-552-boundaries-scope-callbacks
Closed

runningcode wants to merge 1 commit into
no/java-552-boundaries-jvmfrom
no/java-552-boundaries-scope-callbacks

Conversation

@runningcode

@runningcode runningcode commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

PR Stack (Throwable Boundaries)


📜 Description

withScope, withIsolationScope and configureScope keep swallowing the non-fatal exceptions their callback throws. #6657 already made Scopes call ExceptionUtils.rethrowIfFatal first in those catches, with a comment saying why they are broad. This PR documents the behavior and tests it on every path that runs these callbacks:

  • Javadoc on IScopes and the Sentry static methods now says that:
    • if the callback throws, the rest of it is skipped and the exception is logged at ERROR, which by default prints only with debug enabled;
    • fatal errors, such as OutOfMemoryError, are rethrown;
    • before Sentry.init (and, for the static methods, after Sentry.close), withScope and withIsolationScope run the callback on a no-op scope without catching anything, and configureScope doesn't run it at all.
  • Tests: a callback that throws a RuntimeException is swallowed, and one that throws an OutOfMemoryError propagates. This is checked for all three methods through Scopes (also after close()), through the Sentry static methods, and through ScopesAdapter.

ScopesAdapter delegates to the Sentry static methods, which delegate to the current Scopes, so neither needs a catch of its own. NoOpScopes still doesn't catch anything, so before Sentry.init a throwing callback propagates, as it always has.

💡 Motivation and Context

AGENTS.md says that user code wrapped by the SDK should let its own exceptions propagate. For these three callbacks we keep the existing swallowing instead, because changing it would break apps that rely on it. The broad catch now rethrows fatal errors, and the Javadoc tells users how to find out that their callback failed.

💚 How did you test it?

  • ScopesTest and SentryTest, with the new tests above, plus :sentry:javadoc.

📝 Checklist

  • I added GH Issue ID & Linear ID
  • I added tests to verify the changes.
  • No new PII added or SDK only sends newly added PII if sendDefaultPII is enabled.
  • I updated the docs if needed.
  • I updated the wizard if needed.
  • Review from the native team if needed.
  • No breaking change or entry added to the changelog.
  • No breaking change for hybrid SDKs or communicated to hybrid SDKs.
  • Public API changes reviewed by another Mobile SDK team member or implemented according to the develop docs spec.

🔮 Next steps

⚠️ Merge this PR using a merge commit (not squash). Only the bottom of the stack, #6562, is squash-merged into 9.x.x.

#skip-changelog

🤖 Generated with Claude Code

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 <noreply@anthropic.com>
@linear-code

linear-code Bot commented Nov 18, 2026

Copy link
Copy Markdown

JAVA-552

@sentry

sentry Bot commented Nov 18, 2026

Copy link
Copy Markdown

📲 Install Builds

Android

🔗 App Name App ID Version Configuration
SDK Size io.sentry.tests.size 8.64.0 (1) release

⚙️ sentry-android Build Distribution Settings

@runningcode

Copy link
Copy Markdown
Contributor Author

Replaced by independent PRs against 9.x.x, one per kind of change (JAVA-552). This PR's scope-callback Javadoc and tests are now in #6665.

@runningcode
runningcode deleted the no/java-552-boundaries-scope-callbacks branch November 18, 2026 16:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

risk: low PR risk score: low

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant