Skip to main content
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

​
Synheart Emotion Issues

​
Low Confidence Scores

Problem: Emotion detection returns low confidence values (< 0.5). Solutions:
  • Ensure sufficient data window (minimum 60 seconds recommended)
  • Check RR intervals are valid (not all zeros or identical values)
  • Verify heart rate is within normal range (50-200 bpm)
  • Increase window duration for more stable results
  • Check for motion artifacts in biosignal data

​
No Results Returned

Problem: consumeReady() returns empty list. Solutions:
  • Ensure enough data has been pushed (minimum window duration)
  • Check step duration hasn’t elapsed yet
  • Verify data is being pushed correctly (check timestamps)
  • Increase window size if data arrives slowly
  • Check engine initialization was successful

​
High Memory Usage

Problem: SDK uses excessive memory. Solutions:
  • Reduce window duration if possible
  • Clear old results regularly with consumeReady()
  • Use smaller step duration to process more frequently
  • Check for memory leaks in your integration code
  • 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]

​
Python

Problem: Import errors or missing dependencies. Solutions: 
pip install --upgrade synheart-emotion
pip install --upgrade synheart-wear-cli
Problem: Model files not found. Solutions:
  • Verify internet connection for first-time download
  • Check disk space availability
  • Clear cache and reinstall: pip uninstall synheart-emotion && pip install synheart-emotion

​
CLI Issues

​
Command Not Found

Problem: wear command not recognized. Solutions: 
# Verify installation
pip show synheart-wear-cli

# Reinstall if needed
pip install --upgrade synheart-wear-cli

# Check PATH includes Python scripts directory
which wear

​
ngrok Tunnel Fails

Problem: Cannot create ngrok tunnel for webhooks. Solutions:
  • Verify ngrok authtoken is configured: ngrok config check
  • Check ngrok is installed: ngrok version
  • Ensure port 8080 is not in use
  • Try different port: wear webhook start --port 8081

​
OAuth Redirect Fails

Problem: OAuth callback doesn’t reach local server. Solutions:
  • Verify ngrok URL matches vendor redirect URI
  • Check firewall isn’t blocking localhost:8080
  • Ensure local server is running before starting OAuth flow
  • Try manual OAuth flow if automatic fails

​
Performance Issues

​
High CPU Usage

Problem: SDK causes high CPU usage. Solutions:
  • Reduce streaming frequency
  • Increase step duration for emotion engine
  • 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
Author: Israel Goytom