Troubleshooting

The export is undefinedCopy Anchor Link

Check the package and export names:

• ThemeProvider as OvokThemeProvider comes from @ovok/native.
• Ovok comes from @ovok/native/next, and OvokProvider from @ovok/core/next/react. SDK components throw if the provider holds a client that is not the native Ovok.
• There is no @ovok/mobile package alias and no bare native Provider.
• Use the root package or documented subpath, not a source path.

A native module cannot be foundCopy Anchor Link

The JavaScript dependency exists but the installed binary predates the dependency or config plugin. Rebuild a development client after native changes. Expo Go does not contain the SDK's complete native module set.

BLE permission or scan failuresCopy Anchor Link

Check, in order:

1. The app is a development/production native build.
2. react-native-ble-plx and its config plugin are installed.
3. iOS Bluetooth usage descriptions or Android Bluetooth permissions are present.
4. Bluetooth is powered on.
5. The device advertisement's name or localName matches the accepted declaration.
6. The required service UUID is advertised.
7. A second screen or manager is not scanning at the same time.
8. Background mode has service UUID filters.

onError contains the BLE/protocol error and may include deviceData.

A device is found but no reading arrivesCopy Anchor Link

Confirm the exact declaration and measurement protocol:

• the model is the correct entry in SUPPORTED_DEVICES;
• the device is ready to measure or has stored history available;
• oneReadingPerConnection is not suppressing the expected stream;
• the result callback is mounted before connecting;
• for ECG file devices, persist and pass delivered file names;
• for a custom device, verify frame selector, byte order, units, and service UUIDs.

Do not widen a name matcher until the advertisement has been captured and the device protocol is understood.

Health authorization never completesCopy Anchor Link

For HealthKit, check the requested identifiers, capability, usage descriptions, and the provider's notRequested identifiers. For Health Connect, check initialization, the exact record types, and whether the status is refused rather than error.

The sync component intentionally does not import a type whose authorization is still pending. Handle partial authorization instead of treating it as a global failure.

Health import pausesCopy Anchor Link

wifiOnly pauses on cellular data with reason wifi-only. No network pauses with reason offline. Keep the sync component mounted; it resumes when NetInfo reports an acceptable network.

Health import fails with 429 or 503Copy Anchor Link

Health saves retry rate-limit, server and upstream errors (429, 500, 502, 503, 504) up to three times, waiting at least the server's Retry-After value. A 501 means the environment does not have the feature; it is not retried. If the import still fails, onError receives the final error. Check whether the app is importing too many records at once or the service is still unavailable.

Background work does not runCopy Anchor Link

Background work requires all of the following:

• a native build with the correct plugin and permissions;
• durable queue storage;
• a stable iOS restoration identifier;
• service UUIDs for an iOS background scan;
• an Android foreground service for long-lived BLE monitoring;
• a registered Android Health Connect headless task for process-death import;
• restored auth and patient state in headless work;
• acceptance that the OS can defer background execution.

A background task is not a substitute for foreground UI and cannot render a React component after process death.

Results are duplicatedCopy Anchor Link

BLE queue delivery is at least once. Deduplicate on the backend using the queued result's stable id. Do not remove the queue item before the server confirms acceptance.