Android Health Connect SDK Troubleshooting

Common Issues

Health Connect permissions not showing

Symptoms: The permission dialog doesn’t appear when calling requestAuthorization().Solutions:

Ensure Health Connect is installed: Health Connect is pre-installed on Android 14+. On older versions, install it from the Google Play Store.

Set Activity before requesting:

sdk.setActivity(this) // Must be called before requestAuthorization

Verify provider is set:

sdk.setProvider("google") // Must be set before requesting permissions
sdk.requestAuthorization(types = listOf("steps", "heartRate"))

Check min SDK: Your app’s minSdk must be 29 or higher.
Check Health Connect package query: The SDK declares this in its manifest, but verify it merged correctly:
<queries> <package android:name="com.google.android.apps.healthdata" /> </queries>

Samsung Health not available

Symptoms: Samsung Health provider not found or setProvider("samsung") returns false.Solutions:

Samsung devices only: Samsung Health SDK typically only works on Samsung devices.
Samsung Health app must be installed: The user needs the Samsung Health app installed and set up.
Try Health Connect instead: Health Connect works on all Android 10+ devices:
sdk.setProvider("google")

Check available providers:

val providers = sdk.getAvailableProviders()
for (p in providers) {
    Log.d("SDK", "${p["displayName"]}: available=${p["isAvailable"]}")
}

Background sync not working

Symptoms: Data only syncs when the app is in the foreground.Solutions:

Check battery optimization: Many Android manufacturers (Samsung, Xiaomi, Huawei, etc.) aggressively kill background services. Ask users to:
- Go to Settings → Apps → Your App → Battery → Unrestricted
- Or Settings → Battery → Battery Optimization → Your App → Don’t Optimize
Verify notification permission (Android 13+): The SDK uses a foreground service with a notification. On Android 13+, POST_NOTIFICATIONS permission must be granted:
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) { requestPermissions(arrayOf(Manifest.permission.POST_NOTIFICATIONS), 1) }

Check WorkManager status: WorkManager handles background scheduling. Verify it’s not constrained:

val workInfos = WorkManager.getInstance(context)
    .getWorkInfosByTag("health_sync")
    .get()
for (info in workInfos) {
    Log.d("SDK", "Work state: ${info.state}")
}

Lifecycle callbacks: Ensure you’re calling lifecycle methods:

override fun onResume() {
    super.onResume()
    sdk.onForeground()
}
override fun onPause() {
    super.onPause()
    sdk.onBackground()
}

Symptoms: Exception when calling signIn().Solutions:

Check credentials: Ensure you provide either (accessToken + optional refreshToken) or apiKey:

// Token-based (recommended)
sdk.signIn(
    userId = userId,
    accessToken = accessToken,
    refreshToken = refreshToken,
    apiKey = null
)

// OR API key-based
sdk.signIn(
    userId = userId,
    accessToken = null,
    refreshToken = null,
    apiKey = apiKey
)

Check network connectivity: Ensure the device can reach your Open Wearables host.
Check token expiration: Access tokens expire. Ensure your backend generates fresh tokens.

Listen for auth errors:

sdk.authErrorListener = { error ->
    Log.e("SDK", "Auth error: $error")
}

Data not appearing in Open Wearables

Symptoms: Sync seems to complete but data doesn’t show up in the API.Solutions:

Check logs:

sdk.logListener = { message ->
    Log.d("HealthSDK", message)
}

Verify health data exists: Open Health Connect (or Samsung Health) and confirm data exists for the requested types.

Check sync status:

val status = sdk.getSyncStatus()
Log.d("SDK", "Status: $status")

Reset anchors for full sync:
sdk.resetAnchors() sdk.syncNow()
Check permissions: Users may have denied specific data types.

SDK not initialized exception

Symptoms: getInstance() throws because SDK wasn’t initialized.Solution: Ensure initialize() is called before getInstance():

// ✅ Correct - in Application.onCreate()
class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        OpenWearablesHealthSDK.initialize(this)
    }
}

// Then anywhere else:
val sdk = OpenWearablesHealthSDK.getInstance()

Sync doesn't resume after app restart

Symptoms: Sync session lost after app is killed.Solutions:

Ensure configure() is called on launch:

// In Application.onCreate()
val sdk = OpenWearablesHealthSDK.initialize(this)
sdk.configure(host = "https://api.openwearables.io")

Check for resumable sessions:

if (sdk.hasResumableSyncSession()) {
    sdk.resumeSync()
}

Verify EncryptedSharedPreferences: If the device was factory reset or the app’s data was cleared, stored credentials are lost and the user needs to sign in again.

Foreground service notification

Symptoms: A persistent notification appears during sync.Solution: This is expected behavior. The SDK uses a foreground service during active data sync for reliability. The notification disappears once the sync cycle completes. You cannot hide this notification — it’s an Android platform requirement for foreground services.

Battery Optimization

Android’s battery optimization can significantly impact background sync. Here’s how different manufacturers handle it:

Manufacturer	Setting Location	Recommendation
Samsung	Settings → Battery → Background Usage Limits	Allow background activity
Xiaomi	Settings → Battery → App Battery Saver	No restrictions
Huawei	Settings → Battery → App Launch	Manage manually, enable all
OnePlus	Settings → Battery → Battery Optimization	Don’t optimize
Pixel/Stock	Settings → Apps → Battery → Unrestricted	Set to Unrestricted

Consider linking users to dontkillmyapp.com which has device-specific instructions for keeping background services alive.

Testing

Manual Sync Test

// Trigger immediate sync and check results
sdk.syncNow()

// Check status after sync
val status = sdk.getSyncStatus()
Log.d("SDK", "Sent count: ${status["sentCount"]}")
Log.d("SDK", "Completed types: ${status["completedTypes"]}")

Check Stored State

val creds = sdk.getStoredCredentials()
Log.d("SDK", "Stored: $creds")
Log.d("SDK", "Session valid: ${sdk.isSessionValid()}")
Log.d("SDK", "Sync active: ${sdk.isSyncActive()}")

Force Fresh Start

If things are in a bad state:

// Clear everything
sdk.stopBackgroundSync()
sdk.signOut()
sdk.clearSyncSession()
sdk.resetAnchors()

// Re-initialize
sdk.configure(host = "https://api.openwearables.io")

Debugging Tips

Enable Verbose Logging

sdk.logListener = { message ->
    Log.d("HealthSDK", message)
}

sdk.authErrorListener = { error ->
    Log.e("HealthSDK", "Auth error: $error")
}

Check Provider State

val providers = sdk.getAvailableProviders()
for (p in providers) {
    Log.d("SDK", """
        Provider: ${p["displayName"]}
        ID: ${p["id"]}
        Available: ${p["isAvailable"]}
    """.trimIndent())
}

Getting Help

If you’re still experiencing issues:

GitHub Issues

Report bugs or request features on the SDK repository.

Discussions

Ask questions and get help from the community.

When reporting issues, please include:

Android version and device model
SDK version
Health provider used (Samsung Health or Health Connect)
Relevant logs from logListener
Steps to reproduce

Getting started

Architecture

Health Scores

Providers

Rabts Mobile App

Sync SDK

MCP Server

Developer Guides

Configuration

Support

Android Health Connect SDK Troubleshooting

Common Issues

Battery Optimization

Testing

Manual Sync Test

Check Stored State

Force Fresh Start

Debugging Tips

Enable Verbose Logging

Check Provider State

Getting Help

GitHub Issues

Discussions

​Common Issues

​Battery Optimization

​Testing

​Manual Sync Test

​Check Stored State

​Force Fresh Start

​Debugging Tips

​Enable Verbose Logging

​Check Provider State

​Getting Help

GitHub Issues

Discussions

Common Issues

Battery Optimization

Testing

Manual Sync Test

Check Stored State

Force Fresh Start

Debugging Tips

Enable Verbose Logging

Check Provider State

Getting Help