feat(core): [Unhandled Sessions 1] Add Unhandled session state and non-terminating error flag by buenaflor · Pull Request #5919 · getsentry/sentry-java

buenaflor · 2026-08-10T09:49:16Z

PR Stack (Unhandled Sessions)

feat(core): Unhandled Sessions #5915 (collection)
feat(core): [Unhandled Sessions 1] Add Unhandled session state and non-terminating error flag #5919
fix(core): [Unhandled Sessions 2] Don't let a queued SessionStart overwrite a newer session #5920
feat(android): [Unhandled Sessions 3] Add internal non-terminating envelope capture #5921
feat(android): [Unhandled Sessions 4] Add session update API for unsampled hybrid errors #5990

📜 Description

Adds the session protocol's unhandled status to the Session model.

Session.State.Unhandled — an unhandled error the process survived.
A hasNonTerminatingUnhandledError flag (non_terminating_unhandled_error in JSON), set by recordNonTerminatingUnhandledError(), which counts the error without ending the session or changing its status while it is alive.
end() finalizes a flagged session as Unhandled rather than Exited. Crashed and Abnormal still take precedence, and update(Crashed, ...) clears the flag.
clone() and the (de)serializer carry the flag; it is omitted from JSON when unset.

Nothing sets the flag yet, so this PR is inert on its own.

The flag is named for what separates this case from a native crash, which is also unhandled but terminates the process and ends the session as crashed.

💡 Motivation and Context

Hybrid runtimes such as Flutter report handled=false exceptions that do not kill the process. Those currently go through the terminating capture path, which marks the session crashed and starts a replacement even though the app keeps running, incorrectly lowering crash-free session rates.

The protocol has had unhandled for exactly this case since 1.6.0, and Relay accepts it.

💚 How did you test it?

SessionSerializationTest gets a session_unhandled.json fixture covering the full unhandled document, round-tripped through the same serialize/deserialize pair as session.json. Omission when the flag is unset needs no test of its own: the existing session.json has no non_terminating_unhandled_error key and those tests compare exact strings, so a leaked key fails them.

PreviousSessionFinalizerTest covers recovering a flagged previous session, including a native crash escalating it to crashed. EnvelopeCacheTest covers the same precedence through the AbnormalExit and NativeCrashExit recovery paths.

📝 Checklist

I added GH Issue ID & Linear ID
I added tests to verify the changes.
No new PII added or SDK only sends newly added PII if sendDefaultPII is enabled.
I updated the docs if needed.
I updated the wizard if needed.
Review from the native team if needed.
No breaking change or entry added to the changelog.
No breaking change for hybrid SDKs or communicated to hybrid SDKs.

🔮 Next steps

Persistence across process death in #5920, the capture API in #5921.

#skip-changelog

⚠️ Merge this PR using a merge commit (not squash). Only the collection branch is squash-merged into main.

github-actions · 2026-08-10T09:49:51Z

	Messages
📖	Do not forget to update Sentry-docs with your feature once the pull request gets approved.

Generated by 🚫 dangerJS against 7baac41

github-actions · 2026-08-10T09:55:02Z

Performance metrics 🚀

	Plain	With Sentry	Diff
Startup time	368.96 ms	444.00 ms	75.04 ms
Size	0 B	0 B	0 B

Previous results on branch: feat/unhandled-sessions-protocol

Startup times

Revision	Plain	With Sentry	Diff
`0c0646f`	388.59 ms	466.14 ms	77.55 ms
`fa28575`	382.08 ms	460.50 ms	78.42 ms
`4df682c`	376.65 ms	444.88 ms	68.22 ms
`9a469c6`	346.63 ms	425.90 ms	79.28 ms
`4a7952f`	324.85 ms	360.54 ms	35.69 ms
`02a6680`	341.96 ms	461.54 ms	119.58 ms
`97f3c00`	309.04 ms	359.62 ms	50.58 ms

App size

Revision	Plain	With Sentry	Diff
`0c0646f`	0 B	0 B	0 B
`fa28575`	0 B	0 B	0 B
`4df682c`	0 B	0 B	0 B
`9a469c6`	0 B	0 B	0 B
`4a7952f`	0 B	0 B	0 B
`02a6680`	0 B	0 B	0 B
`97f3c00`	0 B	0 B	0 B

sentry · 2026-08-10T10:04:38Z

📲 Install Builds

Android

🔗 App Name	App ID	Version	Configuration
SDK Size	io.sentry.tests.size	8.53.0 (1)	release

⚙️ sentry-android Build Distribution Settings

Copilot

Pull request overview

Adds support in the core Session model for the sessions protocol’s unhandled terminal status (for unhandled errors that do not terminate the process) and introduces an internal flag to persist this condition across serialization and recovery.

Changes:

Add Session.State.Unhandled and internal hasNonTerminatingUnhandledError tracking with recordNonTerminatingUnhandledError().
Update Session.end() to finalize flagged sessions as unhandled (while keeping crashed/abnormal precedence).
Add/extend tests to cover JSON round-tripping, omission when unset, and previous-session finalization behavior.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.

File	Description
`sentry/src/main/java/io/sentry/Session.java`	Adds `Unhandled` session state, internal non-terminating-unhandled flag, serialization/deserialization support, and end/finalization behavior.
`sentry/src/test/java/io/sentry/protocol/SessionSerializationTest.kt`	Adds coverage for round-tripping `unhandled` + flag and ensuring the flag is omitted when unset.
`sentry/src/test/java/io/sentry/PreviousSessionFinalizerTest.kt`	Verifies previous-session finalization results in `unhandled` when flagged, and `crashed` when a native crash marker exists.
`sentry/api/sentry.api`	Updates API dump to reflect the new enum constant and internal methods/keys.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

runningcode

Nice! Thanks for breaking this up

Adds Session.State.Unhandled from the session protocol, plus a pending-unhandled marker that survives serialization. A session carrying the marker finalizes as Unhandled instead of Exited on end(), while Crashed and Abnormal keep taking precedence. Co-authored-by: Cursor <cursoragent@cursor.com>

"Unhandled" alone is ambiguous: a native crash is also an unhandled error, it just terminates the process and so ends the session as crashed rather than unhandled. Name the flag after the property that actually distinguishes the two and match the vocabulary of captureEnvelopeNonTerminating. Also clarify that the setter only restores the flag when rebuilding a session and must not be used to mutate a live one. Co-authored-by: Cursor <cursoragent@cursor.com>

clone() and Session.Deserializer are both inside Session, so they can restore the field directly. Dropping the setter keeps it off the public API surface and makes it impossible to flip the flag on a live session without counting the error and advancing the sequence. Co-authored-by: Cursor <cursoragent@cursor.com>

Every other field is set at construction; the flag was the odd one out, assigned afterwards. A private canonical constructor keeps construction complete without putting the flag on the public API, which a 15-arg public overload would do. Co-authored-by: Cursor <cursoragent@cursor.com>

As a bare noun phrase the field read like it held the error rather than a boolean, most visibly where it is passed as a constructor argument. Co-authored-by: Cursor <cursoragent@cursor.com>

Co-authored-by: Cursor <cursoragent@cursor.com>

The round-trip case duplicated one already added to SessionSerializationTest. Keep JSON concerns in the serialization test and leave SessionTest to state transitions. Co-authored-by: Cursor <cursoragent@cursor.com>

Co-authored-by: Cursor <cursoragent@cursor.com>

It was the only field in Session without the one-line comment the surrounding declarations all carry. Co-authored-by: Cursor <cursoragent@cursor.com>

Co-authored-by: Cursor <cursoragent@cursor.com>

hasNonTerminatingUnhandledError is not final - recordNonTerminating UnhandledError and update() both write it - so setting it through a constructor established no invariant that a plain assignment does not. Both call sites are inside Session, so clone() and the deserializer can assign the field directly, which is what the deserializer already does for unknown. Removes the 15-parameter overload and the javadoc that existed to justify it. The public constructor is unchanged, so sentry.api is too. Co-authored-by: Cursor <cursoragent@cursor.com>

Also swaps assertFalse(serialize(...).contains(...)) for Truth's doesNotContain, which reports the offending json on failure instead of just "expected false". The two new PreviousSessionFinalizerTest cases are left on Mockito argThat, which needs a Boolean predicate rather than an assertion. Co-authored-by: Cursor <cursoragent@cursor.com>

…recovery paths Co-authored-by: Cursor <cursoragent@cursor.com>

Co-authored-by: Cursor <cursoragent@cursor.com>

update() only cleared hasNonTerminatingUnhandledError for Crashed, so an ANR arriving after a non-terminating unhandled error left the marker set on an Abnormal session and serialized it into previous_session.json. The marker only decides how an Ok session is finalized, so any explicit terminal status clears it now. Co-authored-by: Cursor <cursoragent@cursor.com>

`status != State.Ok` stated the mechanism while the comment carried the meaning. An isTerminal helper says it directly and reads the same in recordNonTerminatingUnhandledError, whose javadoc already spoke of terminal states. Co-authored-by: Cursor <cursoragent@cursor.com>

This reverts commit 3347255.

sentry · 2026-08-25T12:37:37Z


      // at this state it might be Crashed already, so we don't check for it.
      if (status == State.Ok) {
-        status = State.Exited;
+        status = hasNonTerminatingUnhandledError ? State.Unhandled : State.Exited;
      }

      if (timestamp != null) {


Bug: A persisted session with State.Unhandled has its end() method called again on recovery, incorrectly overwriting its timestamp and duration.
_{Severity: MEDIUM}

Suggested Fix

In PreviousSessionFinalizer, add a condition to prevent calling session.end() on sessions that are already in a terminal state, such as State.Unhandled or State.Exited. The finalizer should only attempt to end sessions that are still in an State.Ok status.

Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's not valid. Location: sentry/src/main/java/io/sentry/Session.java#L257-L263 Potential issue: When a session is marked with a non-terminating unhandled error, its status becomes `State.Unhandled` after `end()` is called. If the application closes before this session is sent, it gets persisted to disk. Upon the next application launch, the `PreviousSessionFinalizer` processes this session. It lacks a specific check for the `State.Unhandled` status and proceeds to call `session.end()` a second time. This subsequent call overwrites the original `timestamp` and recalculates the `duration` based on the current time, leading to incorrect session analytics data being reported.

markushi · 2026-08-26T14:02:03Z

  private @Nullable String abnormalMechanism;

+  /** Whether an unhandled error occurred that did not terminate the process */
+  private boolean hasNonTerminatingUnhandledError;


this should be volatile, but it's not done anywhere else in this class, so good to keep it as-is.

markushi · 2026-08-26T14:03:39Z

+   * <p>Hybrid SDKs whose unhandled errors do not kill the process. Native Java/Android capture
+   * should not call this.
+   *
+   * @return whether the session was updated, i.e. false if it had already reached a terminal state


buenaflor marked this pull request as ready for review August 11, 2026 12:19

buenaflor requested a review from adinauer as a code owner August 11, 2026 12:19

Copilot AI lite review requested due to automatic review settings August 11, 2026 12:19

buenaflor requested review from 0xadam-brown, markushi, romtsn and runningcode as code owners August 11, 2026 12:19

Copilot started reviewing on behalf of buenaflor August 11, 2026 12:20 View session

Copilot AI reviewed Aug 11, 2026

View reviewed changes

runningcode approved these changes Aug 12, 2026

View reviewed changes

Comment thread sentry/src/test/java/io/sentry/protocol/SessionSerializationTest.kt Outdated

runningcode reviewed Aug 14, 2026

View reviewed changes