Errors

The session SDK has two error surfaces: in-stream error events that end a running session, and exceptions thrown synchronously for API misuse. The error codes are the same in Dart, Kotlin, and Swift.

`SessionErrorCode`

Every SDK has a SessionErrorCode enum whose values serialize to the same snake_case strings:

Dart	Kotlin	Swift	Wire string	Typical cause
`permissionDenied`	`PERMISSION_DENIED`	`.permissionDenied`	`permission_denied`	OS denied a sensor permission (HealthKit, Health Connect, BLE, etc.).
`sensorUnavailable`	`SENSOR_UNAVAILABLE`	`.sensorUnavailable`	`sensor_unavailable`	HR source missing or not connected; no reachable watch.
`lowBattery`	`LOW_BATTERY`	`.lowBattery`	`low_battery`	Device battery too low.
`osTerminated`	`OS_TERMINATED`	`.osTerminated`	`os_terminated`	The OS ended the session.
`invalidState`	`INVALID_STATE`	`.invalidState`	`invalid_state`	API misuse, e.g. starting while a session is running.

Parsing a wire string: Dart SessionErrorCode.fromString(value) throws ArgumentError for an unknown value; Swift uses SessionErrorCode(rawValue:), which returns nil; Kotlin’s SessionEvent.fromMap maps an unknown error_code to INVALID_STATE. The wire format is JSON-style maps (see Watch Protocol); there is no protobuf schema.

In-stream error events

SDK	Type
Dart	`SessionError` (subclass of `SessionEvent`) with `code` and `message`
Kotlin	`SessionErrorEvent` (subclass of `SessionEvent`) with `code` and `message`
Swift	`SessionEvent.sessionError(sessionId:code:message:)`

An error event is terminal: no summary follows it. The Swift AsyncStream and the Dart stream finish after it; the Kotlin SharedFlow does not complete, so collectors stop on it themselves. message is human-readable and platform-specific. Log it, but don’t parse it for control flow — only code is stable.

Who emits them

Source	When	Code
Kotlin / Swift `SynheartSession`	The `BiosignalProvider` throws from `startStreaming` (for example a BLE HRM that is not connected, or Health Connect unavailable). `SessionStarted` has already been emitted; the session ends.	`sensor_unavailable`
Kotlin `WatchSessionRelay`	Play Services unavailable, no connected node accepted the command, or the watch sent nothing within 10 seconds.	`sensor_unavailable`
Companion watch app	Whatever the watch reports; relayed as received.	any
Dart engines	Not emitted in 0.3.0.	—

Wire key

Kotlin toMap() and Swift toDictionary() put the code under error_code. Dart SessionError.toJson() writes it under code, and SessionError.fromJson() reads code, so the Dart decoder does not accept a session_error map that only carries error_code.

Recovery paths

Code	Recovery
`permission_denied`	Request the missing permission with the platform API, then start a new session. The SDK does not retry.
`sensor_unavailable`	Reconnect the HR source or the watch. For a watch, check `getWatchStatus()` (Flutter) or `WatchSessionRelay.status()` (Kotlin) before starting again. On Wear OS, a timeout usually means the companion app is missing or does not share the phone app’s package name and signing certificate.
`low_battery`	User remediation. The SDK does not throttle or downsample.
`os_terminated`	Start a new session. Partial data from the ended session is not recoverable from the SDK.
`invalid_state`	Programmer error. Inspect `message` and the call site.

Thrown exceptions

Dart

class SynheartSessionError implements Exception { ... }
class SessionPermissionDeniedError extends SynheartSessionError { ... }
class SessionSensorUnavailableError extends SynheartSessionError { ... }
class SessionInvalidStateError extends SynheartSessionError { ... }

Exception	When
`SessionInvalidStateError`	`startSession` with a `sessionId` that is already running. `startSession`, `stopSession`, `getStatus`, or `getWatchStatus` after `dispose()`.
`SessionPermissionDeniedError`, `SessionSensorUnavailableError`	Defined but not thrown by the SDK in 0.3.0.

These are thrown directly from the call, not delivered on the stream. stopSession with an unknown id does not throw. ingestHsiMetrics and dispose never throw.

Kotlin

SessionError is a sealed Exception with subclasses PermissionDenied, SensorUnavailable, InvalidState, LowBattery, and OsTerminated, each with a code.

Call	Throws `SessionError.InvalidState` when
`startSession(config)`	Any session is already running (whatever its id), or the instance is disposed.
`stopSession(sessionId)`	No session is running, or the id does not match. (No-op after `dispose()`.)
`SessionConfig.fromMap(map)`	`session_id`, `mode`, or `duration_sec` is missing, or the mode is unknown.

Providers throw SessionError.SensorUnavailable from startStreaming; SynheartSession turns that into a SessionErrorEvent.

Swift

SessionError is an enum (Error) with cases permissionDenied(String), sensorUnavailable(String), invalidState(String), lowBattery(String), and osTerminated(String); code returns the SessionErrorCode.

Call	Throws `SessionError.invalidState` when
`startSession(config:)`	Any session is already running (whatever its id), or the instance is disposed.
`stopSession(sessionId:)`	No session is running, or the id does not match. (No-op after `dispose()`.)
`SessionConfig(from:)`	`session_id`, `mode`, or `duration_sec` is missing, or the mode is unknown.

Distinguishing the two surfaces

Situation	Surface
Duplicate start	Dart: `SessionInvalidStateError` for the same id. Kotlin / Swift: `SessionError.InvalidState` / `.invalidState` for any second start.
Call after `dispose()`	Thrown (see the tables above).
BLE HRM not connected at start (Kotlin / Swift)	Error event with `sensor_unavailable`.
Wear OS watch not answering (Kotlin relay)	Error event with `sensor_unavailable` after 10 seconds.
Watch went out of range (Flutter)	No error — channel errors are swallowed and frames continue with whatever samples arrive.

Channel error swallowing

In Flutter, WatchBiosignalProvider treats event-channel errors as non-fatal, so a brief disconnect does not end the session. Apps that need strict reachability must poll getWatchStatus() and stop the session themselves.

Logging

The Dart SDK only prints from an assert-guarded block (a failed watch stop command), so release builds print nothing. The Kotlin WatchSessionRelay and HealthConnectBiosignalProvider log warnings with android.util.Log. Hosts that need structured logging should log events at the call site.

Lifecycle — when the stream ends and what state follows.
Watch Protocol — the event maps on the wire.

Get Started

Security

Setup

CLI

Synapse

Platform

HSI

Synheart Wear

Synheart Auth

Synheart Core

Synheart Behavior

Syni

Syni Spec

Synheart Session

RAMEN 🍜

Lab Mode

Privacy

Guides

`SessionErrorCode`

In-stream error events

Who emits them

Wire key

Recovery paths

Thrown exceptions

Dart

Kotlin

Swift

Distinguishing the two surfaces

Channel error swallowing

Logging

SessionErrorCode

In-stream error events

Who emits them

Wire key

Recovery paths

Thrown exceptions

Dart

Kotlin

Swift

Distinguishing the two surfaces

Channel error swallowing

Logging

Related

`SessionErrorCode`