Skip to main content

Troubleshooting

The export is undefined​

Check the package and export names:

  • ThemeProvider as OvokThemeProvider comes from @ovok/native.
  • OvokProvider and OvokClient come from @ovok/core.
  • 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 found​

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 failures​

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 arrives​

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 completes​

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 pauses​

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.

Background work does not run​

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 duplicated​

BLE queue delivery is at least once. Deduplicate on the backend using BackgroundSyncResult.id. Do not remove the queue item before the server confirms acceptance.