Skip to main content
Jump straight to your section:

​
CLI / install

​
synheart command not found

After installing the CLI, the binary may not be on your PATH. 
synheart version
command -v synheart
If the second command prints nothing, add the install directory to your shell’s PATH. See Install the CLI for the per-shell snippet.

​
synheart login device flow doesn’t complete

  • Open the URL the CLI prints in a browser; if it 404s, your CLI is talking to the wrong gateway — check SYNHEART_API_URL.
  • Confirm you have a platform account.
  • Run synheart whoami after authorising to confirm the token is cached.

​
Install commands fail with “login required”

install and sync need a valid access token. If you’re getting kicked back to login repeatedly: 
synheart logout
synheart login
If that doesn’t fix it, your token may have expired — the relogin should issue a fresh one.

​
Wearable data

​
Permission denied accessing health data

  • iOS — verify Info.plist has NSHealthShareUsageDescription and HealthKit is enabled in your Xcode capabilities.
  • Android — Health Connect permissions must be granted in system settings, and the app must call requestPermissions() before requesting data.
  • Confirm the user actually granted access through your prompt (don’t assume a stale permission state).

​
SDK initializes but no data arrives

  • The wearable hasn’t synced recently — open its vendor app and force a sync.
  • For cloud-backed vendors (WHOOP, Garmin, Fitbit, Oura), the OAuth token may have expired — re-auth.
  • For BLE HRMs, confirm Bluetooth is on and the device is in range and broadcasting.
  • For Health Connect on Android < 14, the Health Connect app must be installed via the Play Store. The adapter returns an empty snapshot rather than throwing in this case — check HealthConnectAdapter.getAvailabilityStatus().

​
OAuth flow fails

  • Verify OAuth credentials in .env.local or your config file.
  • The redirect URI must match what’s registered in the vendor’s dashboard exactly (including trailing slashes).
  • For local development against a vendor that requires a public redirect URI, run a tunnel (e.g. ngrok) and use its HTTPS URL as the redirect. This is dev-only — never use a tunnel URL in production.
  • Clear browser cookies for the vendor’s auth host and try again.
  • Check the vendor’s API status page for outages.

​
Data shape doesn’t match what your code expects

  • Confirm the SDK version matches the adapter version (mismatches can change the normalised schema).
  • Pin both with synheart sync --check in CI so drift fails the build.
  • The wire format is HSI 1.3 — see HSI overview for the canonical envelope.

​
Platform-specific build issues

​
Flutter

flutter clean
flutter pub get
cd ios && pod install   # iOS only
If iOS permissions still don’t work after a clean build, double-check:
  • Info.plist entries (NSHealthShareUsageDescription, etc.) are present.
  • HealthKit capability is enabled in your Xcode target.
  • The app is signed with a provisioning profile that allows HealthKit.
Synheart Wear’s Flutter bindings also require MainActivity to extend FlutterFragmentActivity (not FlutterActivity) on Android 14+.

​
Android / Kotlin

  • Health Connect unavailable — the Health Connect app must be installed (built-in on Android 14+, otherwise via Play Store). Verify Android API ≥ 21.
  • Gradle / JitPack errors — verify repository URLs in settings.gradle.kts, check the version tag exists on GitHub, then ./gradlew clean.

​
iOS / Swift

  • Swift Package Manager can’t resolve — verify the package URL, confirm the deployment target meets the SDK’s minimum (iOS 13+ for Core / Wear / Session, iOS 12+ for Behavior), then clear the SPM cache: rm -rf ~/Library/Developer/Xcode/DerivedData.
  • HealthKit permissions denied — confirm Info.plist usage descriptions, HealthKit capability is enabled, and that you haven’t previously denied permission in Settings → Privacy → Health → [Your App].

​
Performance

​
High CPU usage

The runtime is designed for low overhead; if you’re seeing CPU spikes, the most common causes are:
  • Streaming frequency too high — drop your push rate or use a longer aggregation window.
  • Foreground inference on the UI thread — make sure SDK calls aren’t blocking the UI; use background isolates / coroutines / queues.
  • Profile first — Synheart.runtimeDiagnostics() exposes live counters so you can see which seam is hot.

​
Battery drain

  • Reduce streaming frequency and use larger aggregation windows.
  • Handle backgrounding correctly — pause non-essential streams when the app isn’t foregrounded.
  • Batch processing where possible instead of per-sample work.

​
Thread-safety crashes

  • Per-handle thread-safety is guaranteed for the runtime — concurrent calls on the same handle are serialised internally. Concurrent calls on different handles run in parallel.
  • App-side: keep SDK calls on a single context (main isolate / main thread / a dedicated queue). Don’t share a single SDK instance across multiple un-synchronised threads.
  • Make sure you’re disposing engines / sessions cleanly on app teardown.

​
Still stuck?

  1. Re-read the relevant SDK guide — the symptoms above cover the common cases, but specific errors may be documented in the per-SDK page.
  2. Search existing issues on github.com/synheart-ai.
  3. Open a discussion or issue against the relevant per-language SDK repo under github.com/synheart-ai.
  4. Contact support@synheart.ai.
When filing an issue, include: SDK version, platform + OS version, device model, the error code (if any — they look like SH-WEAR-...), and the minimum reproduction.