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

# Troubleshooting

> Common issues and fixes, grouped by where you're hitting them.

Jump straight to your section:

* [CLI / install](#cli--install) — `synheart` command not found, login fails, install errors.
* [Wearable data](#wearable-data) — permissions, missing data, OAuth, schema mismatches.
* [Platform-specific build issues](#platform-specific-build-issues) — Flutter / Android / iOS toolchain.
* [Performance](#performance) — high CPU, battery drain, thread-safety errors.
* [Still stuck?](#still-stuck) — where to ask.

## CLI / install

### `synheart` command not found

After installing the CLI, the binary may not be on your `PATH`.

```bash theme={null}
synheart version
command -v synheart
```

If the second command prints nothing, add the install directory to your shell's `PATH`. See [Install the CLI](/setup/install-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](/setup/create-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:

```bash theme={null}
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](/hsi/overview) for the canonical envelope.

## Platform-specific build issues

### Flutter

```bash theme={null}
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](https://github.com/synheart-ai).
3. Open a discussion or issue against the relevant per-language SDK repo under [github.com/synheart-ai](https://github.com/synheart-ai).
4. Contact [support@synheart.ai](mailto: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.