@@ -130,30 +130,31 @@ The repository is organized into multiple modules:
130130
131131### Exception Handling
132132
133- ** Never introduce a new ` catch (Throwable) ` .** Catch the narrowest type the guarded code can
134- actually throw. The repository still contains many pre-existing broad catches; they are legacy,
135- not a precedent to follow.
136-
137- A broad catch swallows ` OutOfMemoryError ` , ` StackOverflowError ` , ` ThreadDeath ` and ` LinkageError ` —
138- conditions the JVM/ART cannot recover from and that leave the process in an undefined state — and
139- it hides real bugs in our own code behind a log line.
140-
141- "The SDK must never crash the host application" is not a reason to catch ` Throwable ` . That goal is
142- served by ` io.sentry.util.ExceptionUtils.rethrowIfFatal ` , which lets the non-recoverable throwables
143- through while leaving everything else for the caller to log or ignore:
144-
145- ``` java
146- try {
147- doSomethingRisky();
148- } catch (Throwable t) {
149- ExceptionUtils . rethrowIfFatal(t);
150- options. getLogger(). log(SentryLevel . ERROR , " Failed to do something risky" , t);
151- }
152- ```
153-
154- Apply that pattern only where a broad catch is genuinely unavoidable — an entry point that runs
155- arbitrary user code or third-party callbacks. Everywhere else, name the exception types. Say in the
156- PR description why the broad catch is necessary.
133+ Inside the SDK, ** never add a broad catch** (` Throwable ` , ` Error ` , ` Exception ` ,
134+ ` RuntimeException ` ). Catch the narrowest type the guarded code can actually throw. The many
135+ existing broad catches are legacy, not precedent: they hide real bugs in our own code and make it
136+ appear that Sentry is broken.
137+
138+ A broad catch is allowed only at a boundary where we can't know what the other side throws. Two
139+ examples:
140+
141+ - public API entry points like ` captureException `
142+ - Android framework calls that cross into another process (` ContentResolver ` , system services)
143+
144+ At a boundary:
145+
146+ - Call ` ExceptionUtils.rethrowIfFatal(t) ` first so ` OutOfMemoryError ` , ` StackOverflowError ` , etc.
147+ are never swallowed. It also rethrows ` LinkageError ` , so code probing an optional ` compileOnly `
148+ dependency must catch the specific subclass (` NoClassDefFoundError ` , ...) before it.
149+ - A code comment is required saying why the catch is broad and what happens on failure (event
150+ dropped, feature disabled, ...).
151+ - If wrapping user code with a broad catch, documentation is ** required** explaining how the user
152+ is expected to discover that the code they wrote isn't working. Both in code and in sentry-docs.
153+ - Logging is not handling: ` options.getLogger() ` is silent unless ` debug ` is enabled, so a failure
154+ that is only logged is invisible in production.
155+
156+ Instrumentation that wraps user code is not a boundary for the user's own exceptions: let them
157+ propagate unchanged.
157158
158159### Testing Requirements
159160- Write comprehensive unit tests for new features
0 commit comments