Skip to main content

​
Common Issues

Symptoms: The health permissions dialog doesn’t appear when calling requestAuthorization().Solutions:
  1. Verify Info.plist configuration: 
    <key>NSHealthShareUsageDescription</key>
<string>This app syncs your health data to your account.</string>
  2. Check HealthKit capability in Xcode:
    • Open ios/Runner.xcworkspace
    • Select target → Signing & Capabilities
    • Ensure HealthKit is listed
  3. Run on physical device: HealthKit doesn’t work in the iOS Simulator. Always test on a real device.
  4. Check provisioning profile: Your Apple Developer account must have HealthKit capability enabled for the App ID.
Symptoms: Permission dialog doesn’t appear on Android.Solutions:
  1. Ensure Health Connect is installed: Health Connect must be installed on the device. It’s pre-installed on Android 14+ but may need to be installed from Play Store on older versions.
  2. Set provider before requesting authorization: 
    await OpenWearablesHealthSdk.setProvider(AndroidHealthProvider.healthConnect);
final authorized = await OpenWearablesHealthSdk.requestAuthorization(
  types: [
    HealthDataType.steps,
    HealthDataType.heartRate,
    HealthDataType.sleep,
  ],
);
// authorized == true  → permissions dialog was shown and accepted
// authorized == false → user denied or dialog failed to appear
print('Permissions granted: $authorized');
  3. Check minSdk version: Your android/app/build.gradle must have minSdk 29 or higher.
  4. Verify the Activity is set (if using native Android directly): The Flutter plugin handles this automatically, but if you see permission launcher issues, try rebuilding the app.
Symptoms: Data only syncs when the app is in the foreground.Solutions:
  1. Verify background modes in Info.plist: 
    <key>UIBackgroundModes</key>
<array>
    <string>fetch</string>
    <string>processing</string>
</array>

<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
    <string>com.openwearables.healthsdk.task.refresh</string>
    <string>com.openwearables.healthsdk.task.process</string>
</array>
  2. Check Background App Refresh setting:
    • Go to iOS Settings → Your App → Background App Refresh
    • Ensure it’s enabled
  3. Check Low Power Mode: Background tasks are suspended when Low Power Mode is active.
  4. Wait for system scheduling: iOS controls when background tasks run. Initial syncs may take 15+ minutes to trigger.
Symptoms: Data only syncs when the app is in the foreground on Android.Solutions:
  1. Check battery optimization: Some Android manufacturers aggressively kill background services. Ask users to disable battery optimization for your app in Settings.
  2. Verify notification permissions: On Android 13+, the SDK uses a foreground service notification during sync. Ensure POST_NOTIFICATIONS permission is granted.
  3. Check provider connection: Verify the health provider is properly connected: 
    final providers = await OpenWearablesHealthSdk.getAvailableProviders();
print(providers);
Symptoms: SignInException when calling signIn().Solutions:
  1. Check token expiration: Access tokens expire. Ensure your backend generates fresh tokens.
  2. Verify credentials: Ensure you’re providing either (accessToken + refreshToken) or apiKey: 
    // Token-based (recommended)
await OpenWearablesHealthSdk.signIn(
  userId: userId,
  accessToken: accessToken,
  refreshToken: refreshToken,
);

// OR API key-based
await OpenWearablesHealthSdk.signIn(
  userId: userId,
  apiKey: apiKey,
);
  3. Check network connectivity: Ensure the device can reach your Open Wearables host.
  4. Check SignInException details: 
    try {
  final user = await OpenWearablesHealthSdk.signIn(
    userId: 'usr_abc123',
    accessToken: accessToken,
    refreshToken: refreshToken,
  );
  print('Signed in as ${user.userId}');
} on SignInException catch (e) {
  // Example output: "Message: Unauthorized" / "Status code: 401"
  print('Message: ${e.message}');
  print('Status code: ${e.statusCode}');
}
Symptoms: Sync completes but data doesn’t show up in the API.Solutions:
  1. Check sync status: 
    final status = await OpenWearablesHealthSdk.getSyncStatus();
print('Sent count: ${status['sentCount']}');
  2. Verify health data exists: Open Apple Health or Health Connect and confirm data exists for the requested types.
  3. Check date range: The SDK syncs data incrementally. New data may not exist yet.
  4. Reset anchors for full sync: 
    await OpenWearablesHealthSdk.resetAnchors();
await OpenWearablesHealthSdk.syncNow();
  5. Check permissions: Users may have denied specific data types even if they approved the overall request.
Symptoms: Exception when calling SDK methods.Solution: Ensure configure() is called before any other SDK methods:
// ✅ Correct order
await OpenWearablesHealthSdk.configure(host: 'https://api.openwearables.io');
await OpenWearablesHealthSdk.signIn(
  userId: 'usr_abc123',
  accessToken: accessToken,
  refreshToken: refreshToken,
);
await OpenWearablesHealthSdk.startBackgroundSync();

// ❌ Wrong - signIn before configure
await OpenWearablesHealthSdk.signIn(
  userId: 'usr_abc123',
  accessToken: accessToken,
  refreshToken: refreshToken,
); // Throws NotConfiguredException
Symptoms: Exception when starting sync without signing in.Solution: Check sign-in status before sync operations:
if (!OpenWearablesHealthSdk.isSignedIn) {
  await OpenWearablesHealthSdk.signIn(
    userId: 'usr_abc123',
    accessToken: accessToken,
    refreshToken: refreshToken,
  );
}
await OpenWearablesHealthSdk.startBackgroundSync();
Symptoms: Samsung Health provider not found on getAvailableProviders().Solutions:
  1. Samsung Health must be installed on the device.
  2. Samsung devices only - Samsung Health is typically only available on Samsung devices.
  3. Try Health Connect instead as it works on all Android 10+ devices: 
    await OpenWearablesHealthSdk.setProvider(AndroidHealthProvider.healthConnect);

​
HealthKit Entitlement Issues (iOS)

If you see “Missing HealthKit entitlement” errors:
  1. In Xcode:
    • Target → Signing & Capabilities → Add HealthKit
    • Check “Background Delivery” for background updates
  2. In Apple Developer Portal:
    • App IDs → Your App → Capabilities
    • Enable HealthKit
  3. Regenerate provisioning profiles after making changes

​
Background Delivery Limitations (iOS)

iOS has strict limits on background execution:
FactorImpact
Battery LevelBackground tasks paused below 20%
Low Power ModeAll background tasks suspended
User BehavioriOS learns when you use the app and schedules accordingly
NetworkBackground tasks require network connectivity
For critical sync operations, prompt users to open the app and trigger syncNow() manually.

​
Testing Background Sync

​
iOS

To test background sync during development:
  1. Run app on device
  2. Navigate to home screen
  3. Wait 15+ minutes (or use Xcode’s debug menu)
  4. Check logs for sync activity
In Xcode, you can simulate background fetch:
  • Debug → Simulate Background Fetch

​
Android

  1. Run app on device or emulator
  2. Minimize the app
  3. The SDK uses WorkManager which should trigger relatively quickly
  4. Check logs via MethodChannelOpenWearablesHealthSdk.logStream

​
Debugging Tips

​
Enable Debug Logging

import 'package:open_wearables_health_sdk/open_wearables_health_sdk_method_channel.dart';

// Listen to SDK logs
MethodChannelOpenWearablesHealthSdk.logStream.listen((message) {
  print('[HealthSDK] $message');
});

// Listen to auth errors
MethodChannelOpenWearablesHealthSdk.authErrorStream.listen((error) {
  print('[HealthSDK] Auth error: ${error['statusCode']} - ${error['message']}');
});

// Log current state
print('Status: ${OpenWearablesHealthSdk.status}');
print('Is signed in: ${OpenWearablesHealthSdk.isSignedIn}');
print('Is sync active: ${OpenWearablesHealthSdk.isSyncActive}');
print('User: ${OpenWearablesHealthSdk.currentUser?.userId}');

​
Check Stored Credentials

final creds = await OpenWearablesHealthSdk.getStoredCredentials();
print('Stored credentials: $creds');

​
Monitor Sync Progress

final status = await OpenWearablesHealthSdk.getSyncStatus();
print('Has resumable session: ${status['hasResumableSession']}');
print('Sent count: ${status['sentCount']}');
print('Is full export: ${status['isFullExport']}');
print('Created at: ${status['createdAt']}');

​
Force Fresh Start

If things are in a bad state: 
// Clear everything and start fresh
await OpenWearablesHealthSdk.stopBackgroundSync();
await OpenWearablesHealthSdk.signOut();
await OpenWearablesHealthSdk.clearSyncSession();
await OpenWearablesHealthSdk.resetAnchors();

// Re-initialize
await OpenWearablesHealthSdk.configure(host: 'https://api.openwearables.io');

​
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:
  • Flutter version (flutter --version)
  • SDK version (from pubspec.lock)
  • Platform (iOS/Android) and OS version
  • Device model
  • Relevant logs and error messages
  • Steps to reproduce