Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.synheart.ai/llms.txt

Use this file to discover all available pages before exploring further.

This guide helps you troubleshoot common issues when using Synheart SDKs.

​
Synheart Wear Issues

​
Permission Denied

Problem: App cannot access health data from wearable device. Solutions:
  • iOS: Check Info.plist has NSHealthShareUsageDescription key
  • Android: Verify Health Connect permissions are granted in system settings
  • Ensure the user has granted permissions through the SDK’s requestPermissions() method
  • Check device compatibility (some devices require specific Android/iOS versions)

​
No Data Received

Problem: SDK initializes but no biometric data is received. Solutions:
  • Verify wearable device is synced and has recent data
  • Check device battery level (low battery may prevent syncing)
  • Ensure device is within Bluetooth range (for direct connections)
  • For cloud APIs (WHOOP, Garmin), verify OAuth tokens are valid
  • Check network connection for cloud-based wearables

​
OAuth Flow Fails

Problem: Cannot complete OAuth authentication for cloud wearables. Solutions:
  • Verify OAuth credentials are correct in .env.local or configuration
  • Check redirect URI matches vendor dashboard settings
  • Ensure ngrok tunnel is active (for localhost development)
  • Clear browser cookies and try again
  • Check vendor API status page for outages

​
Data Format Mismatch

Problem: Received data doesn’t match expected schema. Solutions:
  • Verify SDK version compatibility
  • Check device adapter version matches SDK version
  • Review data normalization logs for warnings
  • Ensure using latest SDK version
  • Ensure proper disposal of engine instances

​
Thread Safety Errors

Problem: Crashes or errors when using SDK from multiple threads. Solutions:
  • Ensure all SDK calls happen on the same thread/context
  • Use proper synchronization mechanisms
  • Check SDK documentation for thread-safety guarantees
  • Consider using a single engine instance with proper locking

​
Platform-Specific Issues

​
Flutter/Dart

Problem: Build errors or missing dependencies. Solutions: 
flutter clean
flutter pub get
cd ios && pod install  # For iOS
Problem: iOS permissions not working. Solutions:
  • Verify Info.plist entries are correct
  • Check HealthKit capability is enabled in Xcode
  • Ensure app is signed with proper provisioning profile

​
Android/Kotlin

Problem: Health Connect not available. Solutions:
  • Verify Health Connect app is installed
  • Check Android version (requires Android 9+)
  • Ensure Health Connect is enabled in system settings
Problem: Build errors with JitPack. Solutions:
  • Verify repository URL in settings.gradle.kts
  • Check version tag exists on GitHub
  • Clear Gradle cache: ./gradlew clean

​
iOS/Swift

Problem: Swift Package Manager cannot resolve dependencies. Solutions:
  • Verify package URL is correct
  • Check minimum iOS version requirement
  • Clear SPM cache: rm -rf ~/Library/Developer/Xcode/DerivedData
  • Update Xcode to latest version
Problem: HealthKit permissions denied. Solutions:
  • Check Info.plist has proper usage descriptions
  • Verify HealthKit capability is enabled
  • Reset permissions: Settings → Privacy → Health → [Your App]

​
CLI Issues

​
Command Not Found

Problem: synheart command not recognized after install. Solutions: 
synheart version
command -v synheart
If not found, ensure the install directory is on your PATH — see Install the CLI.

​
Login fails

Problem: synheart login device flow does not complete. Solutions:
  • Verify the URL printed by the CLI loads in your browser
  • Confirm you have a platform account
  • Check synheart whoami after authorizing

​
Performance Issues

​
High CPU Usage

Problem: SDK causes high CPU usage. Solutions:
  • Reduce streaming frequency
  • Use background threads for processing
  • Profile your app to identify bottlenecks

​
Battery Drain

Problem: App drains device battery quickly. Solutions:
  • Reduce streaming frequency
  • Use appropriate window sizes (not too small)
  • Implement proper background/foreground handling
  • Consider batching data processing

​
Getting Help

If you’re still experiencing issues:
  1. Check Documentation: Review the relevant SDK guide
  2. GitHub Issues: Search existing issues on GitHub
  3. Community: Ask questions in Discussions
  4. Support: Contact support@synheart.ai
When reporting issues, please include:
  • SDK version
  • Platform and version
  • Device model
  • Error messages or logs
  • Steps to reproduce