From 54b5bf7a50474fbdd9e65a10fda88a44f17e7b6b Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Wed, 14 Oct 2026 03:49:18 +0000 Subject: [PATCH 1/2] docs(sdk): Clarify strict mode for callback error isolation Co-Authored-By: Alexander Dinauer --- develop-docs/sdk/foundations/client/hooks/index.mdx | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/develop-docs/sdk/foundations/client/hooks/index.mdx b/develop-docs/sdk/foundations/client/hooks/index.mdx index c03ace61b642d..4fd935db792fb 100644 --- a/develop-docs/sdk/foundations/client/hooks/index.mdx +++ b/develop-docs/sdk/foundations/client/hooks/index.mdx @@ -2,7 +2,7 @@ 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 @@ -10,6 +10,9 @@ spec_depends_on: - id: sdk/telemetry/client-reports version: ">=1.24.0" spec_changelog: + - version: 1.1.1 + date: 2026-10-14 + summary: Clarified that strict mode disables callback error isolation and that events reporting a propagated callback error still run through all callbacks - 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 @@ -122,7 +125,9 @@ 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. Strict mode is a kill switch for the isolation boundary: SDKs **MUST** let the callback's error propagate to the caller unchanged, as if the boundary didn't exist, instead of isolating it. + +If the host application reports that error to Sentry, for example through an unhandled-exception integration, the resulting event **MUST** go through the regular pipeline, including the callback that failed. SDKs **MUST NOT** skip callbacks for that event, because callbacks like `before_send` often remove sensitive data. SDKs don't need to track which callback failed. SDKs **SHOULD** prevent reporting loops, where reporting a callback failure fails the same callback again and keeps producing new events. From 2311af644951d532b0cf37676a2ae53ae802bad3 Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Wed, 14 Oct 2026 08:52:26 +0000 Subject: [PATCH 2/2] docs(sdk): Simplify strict mode loop prevention wording Co-Authored-By: Alexander Dinauer --- develop-docs/sdk/foundations/client/hooks/index.mdx | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/develop-docs/sdk/foundations/client/hooks/index.mdx b/develop-docs/sdk/foundations/client/hooks/index.mdx index 4fd935db792fb..387fb0e21b447 100644 --- a/develop-docs/sdk/foundations/client/hooks/index.mdx +++ b/develop-docs/sdk/foundations/client/hooks/index.mdx @@ -12,7 +12,7 @@ spec_depends_on: spec_changelog: - version: 1.1.1 date: 2026-10-14 - summary: Clarified that strict mode disables callback error isolation and that events reporting a propagated callback error still run through all callbacks + 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 @@ -125,9 +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. Strict mode is a kill switch for the isolation boundary: SDKs **MUST** let the callback's error propagate to the caller unchanged, as if the boundary didn't exist, instead of isolating it. - -If the host application reports that error to Sentry, for example through an unhandled-exception integration, the resulting event **MUST** go through the regular pipeline, including the callback that failed. SDKs **MUST NOT** skip callbacks for that event, because callbacks like `before_send` often remove sensitive data. SDKs don't need to track which callback failed. SDKs **SHOULD** prevent reporting loops, where reporting a callback failure fails the same callback again and keeps producing new events. +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.