Skip to content

Commit 8f4bf15

Browse files
runningcodeclaude
andcommitted
docs: Allow broad catches only at SDK boundaries
Inside the SDK, catch the narrowest type. Broad catches are allowed only at boundaries where the thrown types are unknowable, must call rethrowIfFatal first, and must document what happens on failure. Align BUGBOT.md with AGENTS.md so Bugbot enforces the same policy. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
1 parent 91fbff1 commit 8f4bf15

2 files changed

Lines changed: 43 additions & 31 deletions

File tree

‎.cursor/BUGBOT.md‎

Lines changed: 18 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -13,15 +13,26 @@ rule file in [`.cursor/rules/`](rules) for the area the diff touches (`api`, `op
1313
- While we don't want to crash or hang the host application, we also don't want to leave the host
1414
application in a bad or unrecoverable state. Therefore catch the narrowest type the guarded code
1515
can throw.
16-
- Existing broad catches like `catch (Throwable)` are legacy, not precedent. Where a broad catch is
17-
genuinely unavoidable (an entry point running user code or third-party callbacks), it must call
18-
`ExceptionUtils.rethrowIfFatal(t)` first and a code comment must say why the broad catch is
19-
needed.
16+
- Flag any new broad catch (`Throwable`, `Error`, `Exception`, `RuntimeException`) outside a
17+
boundary where we can't know what the other side throws, e.g. public API entry points like
18+
`captureException`, or Android framework calls that cross into another process
19+
(`ContentResolver`, system services). Existing broad catches are legacy, not precedent. See the
20+
Exception Handling section in `AGENTS.md`.
21+
- A broad catch at a boundary must call `ExceptionUtils.rethrowIfFatal(t)` first and requires a
22+
code comment saying why the catch is broad and what happens on failure (event dropped, feature
23+
disabled, ...).
24+
- A broad catch that wraps user code requires documentation, both in code and in sentry-docs,
25+
explaining how the user is expected to discover that the code they wrote isn't working.
26+
sentry-docs is a separate repository, so ask the author to link the docs PR.
2027
- Code probing for an optional `compileOnly` dependency must catch the specific `LinkageError`
21-
subclass (`NoClassDefFoundError`, `NoSuchMethodError`, ...) only.
28+
subclass (`NoClassDefFoundError`, `NoSuchMethodError`, ...). Flag a probe guarded only by a broad
29+
catch with `rethrowIfFatal`: it rethrows every `LinkageError`, crashing the host app when the
30+
dependency is missing.
31+
- Logging is not handling: `options.getLogger()` is silent unless `debug` is enabled. When a catch
32+
only logs, ask the author what the customer sees when it fires.
2233
- The SDK must never `captureException`/`captureMessage` for its own failures or for exceptions
23-
thrown inside user callbacks (`beforeSend`, `beforeBreadcrumb`, `tracesSampler`, ...). Log via
24-
`options.getLogger()` instead — capturing here loops. See
34+
thrown inside user callbacks (`beforeSend`, `beforeBreadcrumb`, `tracesSampler`, ...) — capturing
35+
here loops. See
2536
[Never capture your own exceptions](https://develop.sentry.dev/sdk/getting-started/principles/#never-capture-your-own-exceptions).
2637
- Flag `System.out`/`System.err`, `printStackTrace()`, and `android.util.Log` in SDK source; use
2738
`options.getLogger().log(...)`.

‎AGENTS.md‎

Lines changed: 25 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -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

Comments
 (0)