feat: Allow users to control Mechanism.Handled for captured exceptions

[vladbrincoveanu]

Closes #3383

Implements the approach agreed in this comment: SDK users get explicit control over Mechanism.Handled, and manually captured exceptions default to handled: true.

API changes

New overloads for explicit control:

• SentrySdk.CaptureException(Exception exception, bool handled)
• SentrySdk.CaptureException(Exception exception, Action<Scope> configureScope, bool handled)
• SentryClientExtensions.CaptureException(this ISentryClient client, Exception ex, bool handled)
• HubExtensions.CaptureException(this IHub hub, Exception ex, Action<Scope> configureScope, bool handled)

The existing signatures are kept, so this is source- and binary-compatible. handled is a required parameter rather than optional: an optional one would be permanently shadowed by the existing exact-match overloads, and replacing those signatures would be binary-breaking.

Behavior

• Explicit wins. Passing handled records that value, overriding any flag previously set on the exception (including via SetSentryMechanism).
• The existing overloads are untouched. They write nothing to Exception.Data, so there is no implicit precedence between a preset flag and a plain CaptureException(ex) call.
• The default moved into MainExceptionProcessor. Any exception no integration claimed is now marked handled: true, replacing the previous "thrown ⇒ true, never thrown ⇒ null" heuristic. This is what fixes the symptom Allow SDK users to control Mechanism.Handled for captured exceptions #3383 opens with: SentrySdk.CaptureException(new Exception()) reported Handled -- and now reports Handled: true, per the protocol docs ("exceptions captured using capture_exception are handled=true"), which are cited at the decision site. Thrown-and-caught exceptions reported Handled: true before and still do.
• CaptureExceptionInternal (the integration capture path) stamps handled: false, since integrations capture exceptions that user code did not handle.
• Terminal semantics are unchanged. See the discussion below on terminal control for user captures and on the WinUI integration, both are proposed as follow-ups rather than expanding this PR's scope.

Testing

Unit tests cover explicit true/false on every capture path, explicit values overriding preset flags, the untouched plain overloads, and the integration-path default. Verify snapshots updated: API approvals for all four target frameworks, the aggregate-exception mechanism snapshot, and the Sentry.DiagnosticSource / Sentry.EntityFramework integration snapshots, where constructed-and-captured exceptions now report Handled: true.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 74.64%. Comparing base (6516897) to head (3663ee5).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5449      +/-   ##
==========================================
+ Coverage   74.62%   74.64%   +0.02%     
==========================================
  Files         512      512              
  Lines       18672    18680       +8     
  Branches     3657     3658       +1     
==========================================
+ Hits        13934    13944      +10     
+ Misses       3865     3863       -2     
  Partials      873      873              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[vladbrincoveanu]

We have a warden failing check.
Could you please have a look @jamescrosswell ?
Warden cannot review this fork pull request because GitHub withholds repository secrets from fork workflows
Thanks.

[cursor]

Unhandled capture crashes sessions

High Severity

Public CaptureException with handled: false stamps only Mechanism.HandledKey and leaves Terminal unset. Session logic treats unhandled-with-unset-terminal as UnhandledTerminal, so a manual capture ends the session as Crashed and aborts the active transaction even though the process kept running.

Additional Locations (1)

• src/Sentry/HubExtensions.cs#L287-L297

 

^{Reviewed by Cursor Bugbot for commit 5e8b0b1. Configure here.}

[vladbrincoveanu]

Confirmed, this is the current behavior: handled: false stamps only Mechanism.HandledKey and leaves Terminal unset. A genuinely unhandled exception (e.g. AppDomain.UnhandledException) sets handled: false with no terminal flag, which counts as a Crash (see SentryEvent.HasUnhandledTerminalException).

Adding terminal control to the CaptureException signature (defaulting Terminal = false for user-parameter captures) would expand the API surface beyond what #3383 asks for, so I kept it out of this PR , but happy to open a follow-up issue for it, if you think the session-crash default is too surprising for manual captures. What do you think? @jamescrosswell

(The related WinUI issue CaptureExceptionInternal overwriting the platform-forwarded Handled flag, has since been fixed in 3663ee5; only the session-terminal question above remains open.)

[jamescrosswell]

OK this is going down a bit of a 🐇 🕳️ - apologies in advance for the long reply...

The TLDR; is that I think we need to expose a way to set both Handled and Terminal (not just Handled).

Detailed response

Terminal exists to determine two things:

1. A session's end status (Release Health)
   a. Only relevant for mobile/desktop/gaming clients (makes no sense for ASP.NET Core)
2. Whether to abort the active

SentryEvent.GetExceptionType() collapses Handled+Terminal into three buckets:

Handled	Terminal	ExceptionType	Consequence
not false	(ignored)	Handled	ReportError() — session stays alive, error count++
false	unset / not false	UnhandledTerminal	EndSession(Crashed) and aborts the active transaction
false	explicitly false	UnhandledNonTerminal	MarkSessionAsUnhandled() — session flagged, but not ended, transaction not aborted

Session Health

So Terminal only matters when Handled: false and it's basically used to distinguish between unhandled and crashed from the perspective of Release Health. In the .net SDK, that's captured via the the SessionEndStatus in the SentryClient:

sentry-dotnet/src/Sentry/SentryClient.cs

Lines 392 to 409 in f02bc53

	var exceptionType = processedEvent.GetExceptionType();
	switch (exceptionType)
	{
	case SentryEvent.ExceptionType.UnhandledNonTerminal:
	_options.LogDebug("Marking session as 'Unhandled', due to non-terminal unhandled exception.");
	_sessionManager.MarkSessionAsUnhandled();
	break;
	case SentryEvent.ExceptionType.UnhandledTerminal:
	_options.LogDebug("Ending session as 'Crashed', due to unhandled exception.");
	scope.SessionUpdate = _sessionManager.EndSession(SessionEndStatus.Crashed);
	break;
	case SentryEvent.ExceptionType.Handled:
	_options.LogDebug("Updating session by reporting an error.");
	scope.SessionUpdate = _sessionManager.ReportError();
	break;
	}

And importantly, unhandled exceptions are terminal by default in the .NET SDK:

sentry-dotnet/src/Sentry/SentryEvent.cs

Lines 223 to 265 in 29ef560

	internal bool HasUnhandledTerminalException()
	{
	// Check if the original exception was unhandled and not explicitly marked as non-terminal
	if (Exception?.Data[Mechanism.HandledKey] is false)
	{
	// If it's unhandled but explicitly marked as non-terminal, return false
	if (Exception.Data[Mechanism.TerminalKey] is false)
	{
	return false;
	}
	// Otherwise, unhandled exceptions are terminal by default
	return true;
	}
	// Check if any Sentry exceptions are unhandled and terminal
	// (handled: false and terminal: not explicitly false)
	return SentryExceptions?.Any(e =>
	e.Mechanism is { Handled: false } &&
	e.Mechanism.Terminal != false
	) ?? false;
	}
	private bool HasUnhandledNonTerminalException()
	{
	// Generally, an unhandled exception is considered terminal.
	// Exception: If it is an unhandled exception but the terminal flag is explicitly set to false.
	// I.e. captured through the UnobservedTaskExceptionIntegration, or the exception capture integrations in the Unity SDK
	if (Exception?.Data[Mechanism.HandledKey] is false)
	{
	if (Exception.Data[Mechanism.TerminalKey] is false)
	{
	return true;
	}
	return false;
	}
	return SentryExceptions?.Any(e =>
	e.Mechanism is { Handled: false, Terminal: false }
	) ?? false;
	}

Transactions

The impact on transactions is not dependent on the app model and so impacts all apps (including ASP.NET Core).

An UnhandledTerminal exception finishes the current transaction as Aborted (except OTel transactions, which the SpanProcessor handles).

• AppDomainUnhandledExceptionIntegration — handled: false, no terminal ⇒ Terminal/Crashed. (Console, generic .NET, and the process is genuinely dying.)
• WinUIUnhandledExceptionIntegration — passes through the platform's Handled bool; if !handled, terminal/Crashed.
• UnobservedTaskExceptionIntegration — the one built-in case that sets terminal: false (async-void / unawaited Task.Run — unhandled but doesn't crash).
• SentryMiddleware and AspNetCoreExceptionProcessor — mark handled: false, no terminal flag ⇒ No session tracking in ASP.NET Core and so all this does is terminate the Transaction with an error state, which is the desired behaviour for a 5xx.

What this means for this PR

CaptureException(ex, handled: false) stamps only HandledKey, leaves Terminal unset, so it always classifies Unhandled as UnhandledTerminal = Crash.

• ASP.NET Core / web: Manual handled: false capture will abort the active transaction, which might be surprising to SDK users!!!
• MAUI / desktop clients: Manual handled: false capture will end the session as Crashed and open a new one, denting the crash-free-sessions rate — even though nothing actually crashed. Again, possibly surprising to SDK users manually setting handled to false.

So I don't think we can expose handled without also exposing a way to set terminal - since without that you allow SDK users to specify UnhandledTerminal (crash) but no way to specify UnhandledNonTerminal (unhandled but not a crash).

[vladbrincoveanu]

Hi James,
Thanks for taking the time to explain this.
I will take care of the comments next week Monday. Should I leave the PR in an opened state until then?

[jamescrosswell]

Yeah it's marked as Changes Requested so all good to leave it open.

Thanks @vladbrincoveanu !

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 1d662b6. Configure here.}

[jamescrosswell]

@vladbrincoveanu thank you very much for the PR... it does raise some tricky problems though - see my inline comments below.

[jamescrosswell]

This would be a change in behaviour. I think it probably makes sense... we can probably do it without making a major release - arguably it's a bug fix rather than an arbitrary change.

@dingsdax do you have any steer?

[jamescrosswell]

Suggest we make this a bit clearer. This method is internal and the mechanism is always set by internal integrations before it's called.

We can add it - I think we should note in the comment that it's defensive only, if we do.

Suggested change

	// Integrations stamp the flag via SetSentryMechanism before calling this (e.g. WinUI forwards the
	// platform's Handled value); only default to unhandled when nothing was declared.
	// Integrations always call `SetSentryMechanism` before calling this method, so
	// this fallback is defensive only. In practice, this code never executes.

[jamescrosswell]

I'd suggest reordering the parameters. The action will likely be a lambda function which could be arbitrarily long/complex. Having the bool as the last parameter would make things harder to read.

Suggested change

	public static SentryId CaptureException(this IHub hub, Exception ex, Action<Scope> configureScope, bool handled)
	public static SentryId CaptureException(this IHub hub, Exception ex, bool handled, Action<Scope> configureScope)

[jamescrosswell]

See related comment above.

Suggested change

	public static SentryId CaptureException(Exception exception, Action<Scope> configureScope, bool handled)
	public static SentryId CaptureException(Exception exception, bool handled, Action<Scope> configureScope)

[jamescrosswell]

OK this is going down a bit of a 🐇 🕳️ - apologies in advance for the long reply...

The TLDR; is that I think we need to expose a way to set both Handled and Terminal (not just Handled).

Detailed response

Terminal exists to determine two things:

1. A session's end status (Release Health)
   a. Only relevant for mobile/desktop/gaming clients (makes no sense for ASP.NET Core)
2. Whether to abort the active

SentryEvent.GetExceptionType() collapses Handled+Terminal into three buckets:

Handled	Terminal	ExceptionType	Consequence
not false	(ignored)	Handled	ReportError() — session stays alive, error count++
false	unset / not false	UnhandledTerminal	EndSession(Crashed) and aborts the active transaction
false	explicitly false	UnhandledNonTerminal	MarkSessionAsUnhandled() — session flagged, but not ended, transaction not aborted

Session Health

So Terminal only matters when Handled: false and it's basically used to distinguish between unhandled and crashed from the perspective of Release Health. In the .net SDK, that's captured via the the SessionEndStatus in the SentryClient:

sentry-dotnet/src/Sentry/SentryClient.cs

Lines 392 to 409 in f02bc53

	var exceptionType = processedEvent.GetExceptionType();
	switch (exceptionType)
	{
	case SentryEvent.ExceptionType.UnhandledNonTerminal:
	_options.LogDebug("Marking session as 'Unhandled', due to non-terminal unhandled exception.");
	_sessionManager.MarkSessionAsUnhandled();
	break;
	case SentryEvent.ExceptionType.UnhandledTerminal:
	_options.LogDebug("Ending session as 'Crashed', due to unhandled exception.");
	scope.SessionUpdate = _sessionManager.EndSession(SessionEndStatus.Crashed);
	break;
	case SentryEvent.ExceptionType.Handled:
	_options.LogDebug("Updating session by reporting an error.");
	scope.SessionUpdate = _sessionManager.ReportError();
	break;
	}

And importantly, unhandled exceptions are terminal by default in the .NET SDK:

sentry-dotnet/src/Sentry/SentryEvent.cs

Lines 223 to 265 in 29ef560

	internal bool HasUnhandledTerminalException()
	{
	// Check if the original exception was unhandled and not explicitly marked as non-terminal
	if (Exception?.Data[Mechanism.HandledKey] is false)
	{
	// If it's unhandled but explicitly marked as non-terminal, return false
	if (Exception.Data[Mechanism.TerminalKey] is false)
	{
	return false;
	}
	// Otherwise, unhandled exceptions are terminal by default
	return true;
	}
	// Check if any Sentry exceptions are unhandled and terminal
	// (handled: false and terminal: not explicitly false)
	return SentryExceptions?.Any(e =>
	e.Mechanism is { Handled: false } &&
	e.Mechanism.Terminal != false
	) ?? false;
	}
	private bool HasUnhandledNonTerminalException()
	{
	// Generally, an unhandled exception is considered terminal.
	// Exception: If it is an unhandled exception but the terminal flag is explicitly set to false.
	// I.e. captured through the UnobservedTaskExceptionIntegration, or the exception capture integrations in the Unity SDK
	if (Exception?.Data[Mechanism.HandledKey] is false)
	{
	if (Exception.Data[Mechanism.TerminalKey] is false)
	{
	return true;
	}
	return false;
	}
	return SentryExceptions?.Any(e =>
	e.Mechanism is { Handled: false, Terminal: false }
	) ?? false;
	}

Transactions

The impact on transactions is not dependent on the app model and so impacts all apps (including ASP.NET Core).

An UnhandledTerminal exception finishes the current transaction as Aborted (except OTel transactions, which the SpanProcessor handles).

• AppDomainUnhandledExceptionIntegration — handled: false, no terminal ⇒ Terminal/Crashed. (Console, generic .NET, and the process is genuinely dying.)
• WinUIUnhandledExceptionIntegration — passes through the platform's Handled bool; if !handled, terminal/Crashed.
• UnobservedTaskExceptionIntegration — the one built-in case that sets terminal: false (async-void / unawaited Task.Run — unhandled but doesn't crash).
• SentryMiddleware and AspNetCoreExceptionProcessor — mark handled: false, no terminal flag ⇒ No session tracking in ASP.NET Core and so all this does is terminate the Transaction with an error state, which is the desired behaviour for a 5xx.

What this means for this PR

CaptureException(ex, handled: false) stamps only HandledKey, leaves Terminal unset, so it always classifies Unhandled as UnhandledTerminal = Crash.

• ASP.NET Core / web: Manual handled: false capture will abort the active transaction, which might be surprising to SDK users!!!
• MAUI / desktop clients: Manual handled: false capture will end the session as Crashed and open a new one, denting the crash-free-sessions rate — even though nothing actually crashed. Again, possibly surprising to SDK users manually setting handled to false.

So I don't think we can expose handled without also exposing a way to set terminal - since without that you allow SDK users to specify UnhandledTerminal (crash) but no way to specify UnhandledNonTerminal (unhandled but not a crash).