Error codes
Every HealthConnectorErrorCode the SDK can raise, the exception it arrives as, why it happens, and what to do about it. Paste the code from your stack trace into the search box.
13 of 13 error codes
permissionNotGrantedAndroid & iOSThrown as
AuthorizationException- Why it happens
- The user denied the permission, revoked it later, or never answered the prompt.
- How to recover
- Call requestPermissions() again, or send the user to the platform settings screen if they previously declined.
permissionNotDeclaredAndroid & iOSFix in your app configThrown as
ConfigurationException- Why it happens
- A required permission is missing from AndroidManifest.xml, or a usage description is missing from Info.plist.
- How to recover
- Add the missing declaration to your app configuration and rebuild. This never resolves itself at runtime.
healthServiceUnavailableAndroid & iOSThrown as
HealthServiceUnavailableException- Why it happens
- The device has no health store — Health Connect is unsupported, or HealthKit is absent (iPad).
- How to recover
- Check HealthConnector.getHealthPlatformStatus() at startup and hide health features gracefully.
healthServiceRestrictedAndroid & iOSThrown as
HealthServiceUnavailableException- Why it happens
- System policy blocks health data access — for example parental controls or an MDM profile.
- How to recover
- Disable health features and explain to the user that a device policy is blocking access.
healthServiceNotInstalledOrUpdateRequiredAndroid onlyThrown as
HealthServiceUnavailableException- Why it happens
- The Health Connect app is not installed, or its version is older than the SDK requires.
- How to recover
- Prompt the user and call HealthConnector.launchHealthAppPageInAppStore().
healthServiceDatabaseInaccessibleiOS onlyRetryableThrown as
HealthServiceException- Why it happens
- The device is locked, so the encrypted health database cannot be opened.
- How to recover
- Defer the operation until the app is foregrounded and unlocked, then retry.
ioErrorAndroid onlyRetryableThrown as
HealthServiceException- Why it happens
- Device storage I/O failed while reading or writing records.
- How to recover
- Retry with exponential backoff.
remoteErrorAndroid onlyRetryableThrown as
HealthServiceException- Why it happens
- IPC with the Health Connect service failed.
- How to recover
- Retry — this is usually a transient system condition.
rateLimitExceededAndroid onlyRetryableThrown as
HealthServiceException- Why it happens
- The app exhausted its Health Connect API quota.
- How to recover
- Back off exponentially and batch your reads and writes more aggressively.
dataSyncInProgressAndroid onlyRetryableThrown as
HealthServiceException- Why it happens
- Health Connect is syncing and has locked the data store.
- How to recover
- Retry after a short delay.
invalidArgumentAndroid & iOSThrown as
InvalidArgumentException- Why it happens
- A parameter was invalid, a record was malformed, or a sync token expired.
- How to recover
- Validate input before calling. For an expired sync token, restart the sync with syncToken: null.
unsupportedOperationAndroid & iOSThrown as
UnsupportedOperationException- Why it happens
- The operation does not exist on this platform or OS version — for example updating a record on iOS.
- How to recover
- Check the @supportedOn annotations before calling, and branch on HealthConnector.healthPlatform.
unknownErrorAndroid & iOSThrown as
UnknownException- Why it happens
- An unclassified internal failure.
- How to recover
- Log the message and stack trace, and open a GitHub issue if it reproduces.
Reading the badges
Fix in your app config means no runtime handling will help. The permission is missing from AndroidManifest.xml, or a usage description is missing from Info.plist. Only a rebuild resolves it.
Retryable means the store failed transiently and the same call is likely to succeed shortly. Use exponential backoff — a tight retry loop against rateLimitExceeded makes the situation worse. There is a ready-made helper in Handle errors.
Codes with neither badge need a decision: either the user must act (permissionNotGranted) or your code must change (unsupportedOperation).