Unity troubleshooting
Start with the result object, current capability, platform, and whether the evidence came from the Editor or a physical device. Do not include raw health records or stable record IDs in diagnostics.
The Setup Wizard did not open
Section titled “The Setup Wizard did not open”Wait for import and compilation to finish, then select **Window > HealthBridge
Setup Wizard**. Confirm the
.unitypackagewas imported completely and that the Console has no compile errors from unrelated scripts.
Initialization fails only on Android
Section titled “Initialization fails only on Android”Android player builds cannot use AutoInitializeAsync. Confirm that the first
scene contains HealthBridgeInitializer, it references the intended settings
asset, and Initialize On Awake is enabled. Also confirm Health Connect is
installed and current and that the user can grant the core exercise and
heart-rate read permissions.
Initialization succeeds but a feature is unavailable
Section titled “Initialization succeeds but a feature is unavailable”Initialization proves the provider is ready, not that every optional feature is
available. Call HealthBridgeService.Provider.Supports before routes, writes,
deletes, or monitoring. On Android, inspect the feature’s permission outcome
from HealthBridgeEvents.OnPermissionsResolved.
A read succeeds with no records
Section titled “A read succeeds with no records”An empty successful result is not automatically an error. Check the requested time window, type ID, device synchronization, and whether the source app has records. On iOS, read authorization is intentionally ambiguous and a denial may also appear empty. Present a neutral empty state with setup and retry guidance.
A read or write returns an error
Section titled “A read or write returns an error”Check Success before consuming the payload. Classify the redacted error as a
configuration, permission, unsupported-capability, invalid-input, native, or
transient failure. See
errors and recovery for retry
guidance.
The Editor works but the device does not
Section titled “The Editor works but the device does not”The Editor uses mocks. iOS needs a physical device, HealthKit-capable App ID, matching provisioning, entitlement, and meaningful usage descriptions. Android needs Health Connect, the initializer, and generated manifest permissions. Use the device validation checklist to separate mock evidence from native evidence.
Workout routes are missing
Section titled “Workout routes are missing”Check HealthCapability.WorkoutRoutes, confirm the workout has a route, and
handle RequiresUserConsent. Routes may be absent, partial, or withheld even
when the workout summary is available.
Delete fails after a successful write
Section titled “Delete fails after a successful write”Delete only records the app owns, keep the returned identifier securely for the
shortest necessary time, and check HealthCapability.DeleteData. A platform may
reject deletion for records written elsewhere.
Heart-rate data is delayed or missing
Section titled “Heart-rate data is delayed or missing”The base SDK’s monitoring path is provider-driven and does not guarantee a continuous live stream. Confirm capability and permission, then allow for watch or platform synchronization delays. Mark the last value stale rather than presenting it as current.
UI changes after its screen was closed
Section titled “UI changes after its screen was closed”HealthBridge events arrive on Unity’s main thread, but async work can still
finish after navigation or object replacement. Unsubscribe delegates in
OnDisable or OnDestroy, use a request generation or cancellation guard, and
discard completions that no longer belong to the active screen.
What to include in a support report
Section titled “What to include in a support report”Include Unity and HealthBridge package versions, platform and OS, device model, failed operation, requested type IDs, capability result, and redacted error text. Never include raw samples, record IDs, routes, tokens, or full native payloads.