Errors

The behavior SDK has a small, mostly-quiet error surface. Most “failures” manifest as zero-valued metrics or empty event streams rather than thrown exceptions — by design, since the SDK is consent-gated and may run inside hosts that haven’t granted permissions yet.

​

Surfaces

​

Synchronous exceptions

The Dart SDK throws standard StateError / ArgumentError for misuse: The Kotlin SDK uses IllegalStateException and IllegalArgumentException; Swift uses Swift’s standard precondition failures with descriptive messages.

​

Permission failures

The SDK does not throw when a platform permission is missing. Instead: Hosts query availability via:

• checkNotificationPermission() / requestNotificationPermission() (Android).
• checkCallPermission() / requestCallPermission() (Android).

iOS doesn’t have user-facing permissions for the surfaces the SDK uses; silent fallback is the same.

​

Native channel errors

Method-channel calls can fail if the native plugin isn’t registered (e.g. desktop builds without the platform layer). Dart’s PlatformException: Kotlin and Swift surface these as their own typed errors at the Kotlin / Swift bridge.

​

Motion classifier errors

When enableMotionLite = true and the bundled ONNX model fails to load:

• The failure is logged with the underlying ORT error.
• motionState stays null for the session.
• getCurrentStats() does not include motion-state fields.
• onEvent and other behavioral metrics continue normally.

The SDK does not retry model loading mid-session; restart the session (or initialize() after dispose()) to retry.

​

Runtime gate drops

When the host wires the SDK into synheart-core → the Synheart runtime, behavior events pass through the runtime’s consent gate. If Behavior consent is not granted, the runtime drops events at the engine seam silently. The SDK sees no error — events fire on onEvent, but the runtime never persists or aggregates them. This is intentional: SDK-side telemetry remains coherent (UIs still see live events) while the privacy boundary is enforced past the SDK.

​

Validation invariants

The SDK guarantees, regardless of error state:

• Numeric metrics are always finite and within their declared range (NaN/inf clamped to 0.0).
• BehaviorSessionSummary is always emitted on session.end(), even when no events flowed.
• BehaviorEvent.eventId is unique within a session.
• BehaviorEvent.timestamp is ISO-8601 UTC.

If any of these break, file a bug.

​

Related

• Behavior Overview — config flags that gate each surface.
• Threat Model — what’s collected and what’s not.
• Metric Definitions — numerical stability rules.
• Consent System — runtime-side Behavior gate.