Unreal Engine troubleshooting
The plugin or wizard is missing
Section titled “The plugin or wizard is missing”Confirm HealthBridge is enabled in Edit > Plugins, restart the editor, then select Tools > HealthBridge > Setup Wizard.
If the plugin cannot load, confirm the project can compile source plugins for its Unreal Engine version and inspect the first HealthBridge module error rather than later dependent failures.
Initialization returns false
Section titled “Initialization returns false”In the editor, confirm the mock provider is selected. On a device, check the platform setup, required core permission, native plugin packaging, and provider availability. Do not repeatedly initialize every frame.
The sample works in PIE but not on mobile
Section titled “The sample works in PIE but not on mobile”PIE uses mock data. iOS needs a physical device, HealthKit-capable App ID, matching provisioning, entitlement, and app-specific usage descriptions. Android needs Health Connect and final-manifest declarations for each requested health permission. See Unreal Engine mobile platform setup.
Android has a missing permission
Section titled “Android has a missing permission”Check permission rows in Project Settings > Plugins > HealthBridge and the
final generated Android manifest. Health Connect cannot offer a type whose
android.permission.health.* declaration is missing.
If the declaration exists, confirm Health Connect is installed and current, then review its granted and denied permissions for the exact package.
iOS returns no records
Section titled “iOS returns no records”Apple can decline a per-type read without exposing that choice to the app. Handle empty results safely and direct the player to iOS Health privacy settings.
Heart-rate data is delayed or missing
Section titled “Heart-rate data is delayed or missing”HealthBridge does not guarantee real-time heart-rate tracking. Health platforms and connected devices can synchronize samples after they are recorded, so an active workout can temporarily show delayed or empty results. Confirm the heart-rate permission is enabled, then refresh or retry after the platform has synchronized the data.
A read succeeds but returns no samples
Section titled “A read succeeds but returns no samples”Treat this as a valid empty state. The selected time range may contain no data, the platform may not have synchronized, or iOS may be hiding a declined read type. Do not claim that the player granted access or has no health records.
A value is always zero
Section titled “A value is always zero”Check whether the expected key exists in FHealthDataSample.Values. Missing
fields should remain unavailable instead of being displayed as measured zero.
Use the sample helper functions and consult the
data-type reference.
A workout is missing distance, calories, or steps
Section titled “A workout is missing distance, calories, or steps”Those fields are optional and guarded by bHas... flags. Source platforms and
devices do not populate every metric. Hide unavailable metrics.
A workout route asks for consent
Section titled “A workout route asks for consent”Android Health Connect can require route-specific consent. Explain why the route is needed, complete the platform flow, and retry. Preserve the workout if the player declines.
A write works in the editor but fails on a device
Section titled “A write works in the editor but fails on a device”The mock provider does not prove platform write permission. Check registry write support, provider capability, direction-specific permission, final Android manifest or iOS HealthKit update configuration, and the result’s sanitized error.
A delete fails
Section titled “A delete fails”Keep the record visible until deletion succeeds. HealthKit permits deletion only for objects written by the current app, and Android deletion requires a valid record ID. Prefer queries created from a returned sample or workout so ownership information is preserved.
Blueprint callbacks appear more than once
Section titled “Blueprint callbacks appear more than once”Bind delegates once for the owning object’s lifetime and unbind during teardown. Do not bind again on every screen refresh or initialization retry.
The UI updates after its screen closed
Section titled “The UI updates after its screen closed”Completion callbacks run on the game thread but can outlive a screen. Track the owning screen or request state and ignore stale completions after teardown.
When reporting an issue, include Unreal and plugin versions, platform and OS, the failed operation, and redacted error text—never raw health data or IDs.
For result-state guidance, see Errors, empty results, and recovery.