Skip to content

fix(core): [Throwable Boundaries 1] Rethrow fatal errors at core SDK boundaries - #6657

Closed
runningcode wants to merge 3 commits into
no/java-552-narrow-unsafe-throwable-catchesfrom
no/java-552-boundaries-core
Closed

runningcode wants to merge 3 commits into
no/java-552-narrow-unsafe-throwable-catchesfrom
no/java-552-boundaries-core

Conversation

@runningcode

@runningcode runningcode commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

PR Stack (Throwable Boundaries)


📜 Description

The remaining catch (Throwable) sites in the core sentry module are boundaries: public API entry points (Scopes), user callbacks, event processors, integrations, and data written by earlier launches, other processes or hybrid SDKs. They also swallowed OutOfMemoryError, StackOverflowError and LinkageError. This PR handles all 71 of them:

  • 67 boundaries now call ExceptionUtils.rethrowIfFatal first, with a comment saying why the catch is broad and what is lost when it fails.
  • LinkageError arms, so a missing or mismatched optional dependency keeps the old handling:
    • Scopes.close, around each integration's close(), like Integration.register in Sentry.init.
    • The six event processor loops in SentryClient. Without it, a NoClassDefFoundError in one SDK processor would propagate out of every capture call.
  • Narrowed (2): attaching a client report (IOException), and SentryEnvelopeItemHeader.getMetaLength (Exception, which the item's lazy data factory declares).
  • Removed (2): the catches in ClientReportRecorder.recordLostEnvelope and recordLostEvent, which guard nothing their callees don't already catch.
  • Javadoc on the user-facing callbacks says what is dropped when they throw, that the error is logged at ERROR (which prints only with debug enabled), and that fatal errors are rethrown. This follows the develop docs' "Callback Error Isolation" section:
    • SentryOptions: BeforeSendCallback, BeforeSendTransactionCallback, BeforeSendReplayCallback, BeforeBreadcrumbCallback, OnOversizedEventCallback, OnDiscardCallback, TracesSamplerCallback, ProfilesSamplerCallback, Logs.BeforeSendLogCallback, Metrics.BeforeSendMetricCallback
    • SentryReplayOptions.BeforeErrorSamplingCallback, ScopeCallback.run, EventProcessor, Sentry.OptionsConfiguration.configure

withScope, withIsolationScope and configureScope still swallow the callback's non-fatal exceptions, as before.

💡 Motivation and Context

rethrowIfFatal also rethrows LinkageError, so it could only be added once the sites where a LinkageError is expected were narrowed. #6562 does that, so this stack is based on it. The sites that #6564 narrows are left alone here.

💚 How did you test it?

  • The full :sentry:test suite, plus :sentry:compileJava and :sentry:javadoc.
  • New tests check that a fatal error propagates from beforeSend, beforeBreadcrumb, an event processor, the traces and profiles samplers, a ScopeCallback and a client, while a RuntimeException is still logged. Other tests check that a NoClassDefFoundError from one integration's close still lets the next one close, and that an SDK event processor hitting a LinkageError is skipped and the event is still sent.

📝 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

  • The rest of the stack applies the same pass to sentry-android-core, replay with NDK and SQLite, and the JVM integrations.
  • The sentry-docs note on how users find failing callbacks comes with the 9.0.0 migration guide.

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

🤖 Generated with Claude Code

runningcode and others added 2 commits November 18, 2026 12:07
The broad catches in the core SDK sit at boundaries where we can't know
what the other side throws: public API entry points, user callbacks,
event processors, integrations, and data written by other launches,
processes or hybrid SDKs. They also swallowed OutOfMemoryError,
StackOverflowError and LinkageError. Call ExceptionUtils.rethrowIfFatal
first at each one, and say in a comment why it is broad and what is lost
when it fails.

- Integration close in Scopes.close catches LinkageError first, like
  Integration.register in Sentry.init, so a missing optional dependency
  doesn't stop the other integrations from closing.
- The user-facing callbacks, ScopeCallback, EventProcessor and
  OptionsConfiguration document that a throwing callback only shows up
  in the debug log, and that fatal errors are rethrown.
- Narrow the two catches whose failures are known: attaching a client
  report (IOException) and the envelope item meta length (Exception).
- Remove the catches in ClientReportRecorder.recordLostEnvelope and
  recordLostEvent, which guard nothing the callees don't already catch.

Refs JAVA-552

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Event processors come from integrations that probe optional
dependencies, as well as from the app. With rethrowIfFatal alone, a
NoClassDefFoundError in one SDK processor would propagate out of every
capture call to the app. Handle a LinkageError like any other processor
failure instead, as Integration.register does in Sentry.init.

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

@github-actions

Copy link
Copy Markdown
Contributor

🚨 Detected changes in high risk code 🚨

High-risk code has higher potential to break the SDK and may be hard to test. To prevent severe bugs, apply the rollout process for releasing such changes and be extra careful when changing and reviewing these files:

  • sentry/src/main/java/io/sentry/transport/HttpConnection.java

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@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 sites are now in: the boundaries, the callback Javadoc, the ClientReportRecorder attach narrowing and the Behavioral Changes entry in #6665, the LinkageError arms in Scopes.close (with the catch around the whole shutdown) and the six SentryClient event processor loops in #6666, the SentryEnvelopeItemHeader meta length narrowing in #6669, and the two removed ClientReportRecorder catches in #6668.

@runningcode
runningcode deleted the no/java-552-boundaries-core 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: high PR risk score: high

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant