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.
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:
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

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.