Skip to content

docs(sdk): Clarify strict mode for callback error isolation #19967

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sentry-junior wants to merge 2 commits into
base: master
Choose a base branch
from
Open

docs(sdk): Clarify strict mode for callback error isolation #19967

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
54b5bf7
docs(sdk): Clarify strict mode for callback error isolation
sentry-junior[bot] Oct 14, 2026
2311af6
docs(sdk): Simplify strict mode loop prevention wording
sentry-junior[bot] Oct 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions develop-docs/sdk/foundations/client/hooks/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,17 @@
title: Hooks
description: Client lifecycle hooks, the on/emit subscription system, user-facing callbacks like before_send and the samplers, and how SDKs isolate errors raised inside them.
spec_id: sdk/foundations/client/hooks
spec_version: 1.1.0
spec_version: 1.1.1
spec_status: candidate
spec_depends_on:
- id: sdk/foundations/client
version: ">=3.0.0"
- id: sdk/telemetry/client-reports
version: ">=1.24.0"
spec_changelog:
- version: 1.1.1
date: 2026-10-14
summary: Replaced the strict mode requirement to skip the failed callback with a requirement to prevent error loops between failing callbacks and uncaught exception handlers
- version: 1.1.0
date: 2026-08-31
summary: Added callback error isolation requirements, the per-callback failure matrix, and the `callback_error` client report for dropped items; widened scope to all user-provided callbacks
Expand Down Expand Up @@ -122,7 +125,7 @@ When a user-provided callback fails due to a recoverable error, SDKs:
- **SHOULD** drop the data passed to the callback. For callbacks that do not support dropping data (e.g. `before_send_span`), SDKs **SHOULD** instead send the data to Sentry unchanged.
- **SHOULD** record a client report with reason `callback_error` for all data dropped as a result of the callback error.

SDKs **MAY** offer an opt-in strict mode, disabled by default. In strict mode, a callback failure **MUST** propagate as an unhandled error of the host application instead of being isolated. SDKs **MUST NOT** pass the event reporting that error through the callback that failed. If any callback fails while processing that event, or data the SDK creates while reporting it (such as breadcrumbs), SDKs **MUST** isolate that failure instead of propagating it.
SDKs **MAY** offer an opt-in strict mode, disabled by default. In strict mode, a callback failure **MUST** propagate as an unhandled error of the host application instead of being isolated. SDKs **MUST** prevent error loops caused by a failing callback and an uncaught exception handler, for example when the handler captures the propagated error and the resulting event fails the same callback again.

</SpecSection>

Expand Down
Loading