Skip to main content

Troubleshooting

Common issues and their solutions.

Installation Issues​

"Module not found" error​

Expo:

# Clean and rebuild
npx expo prebuild --clean
npx expo run:ios  # or run:android

Bare React Native:

# iOS
cd ios && pod install && cd ..
npx react-native run-ios

# Android - clean build
cd android && ./gradlew clean && cd ..
npx react-native run-android

CocoaPods issues on iOS​

cd ios
pod deintegrate
pod cache clean --all
pod install

Runtime Issues​

"Health data not available"​

iOS Simulator: HealthKit is not available in the iOS Simulator. Test on a physical device.

Android Emulator:

  1. Install Health Connect from the Play Store
  2. Open Health Connect and grant permissions to itself
  3. Add some test data

Check availability first:

const status = await HealthX.checkAvailability();
if (!status.isAvailable) {
  console.log('Reason:', status.reason);
  console.log('Message:', status.message);
}

"HealthX not initialized"​

Make sure to call initialize() before accessing any data:

// Wrong
const sessions = await HealthX.sleep.getSessions({ ... }); // Error!

// Correct
await HealthX.initialize();
const sessions = await HealthX.sleep.getSessions({ ... });

Empty results​

  1. Check permissions:
const status = await HealthX.getPermissionStatus();
console.log('Read permission:', status.sleep?.read);
  1. Check date range:
// Make sure dates are valid ISO strings
const sessions = await HealthX.sleep.getSessions({
  startDate: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString(),
  endDate: new Date().toISOString(),
});
  1. Verify data exists:
    • iOS: Open Health app → Browse → Sleep
    • Android: Open Health Connect → Data and access → Sleep

"Writing sleep data is not supported on iOS"​

This is expected. iOS HealthKit doesn't allow third-party apps to write sleep data.

// Check before writing
if (HealthX.supportsWrite()) {
  await HealthX.sleep.writeSession({ ... });
} else {
  // Show alternative UI or message
}

Permission Issues​

Permission dialog doesn't appear​

iOS:

  • Ensure NSHealthShareUsageDescription is in Info.plist
  • Try uninstalling and reinstalling the app

Android:

  • Ensure permissions are in AndroidManifest.xml
  • Check that Health Connect is installed

Permission always shows "not_determined" (iOS)​

This is normal behavior. iOS HealthKit doesn't expose whether read permission was denied. You can only know if permission was definitely granted by successfully reading data.

User can't grant permissions​

Direct them to the health settings:

await HealthX.openHealthSettings();

Data Issues​

Sleep stages are empty or incomplete​

iOS:

  • Detailed stages (DEEP, REM, LIGHT) require iOS 16+ and Apple Watch
  • Older iOS versions only have IN_BED and ASLEEP

Android:

  • Stages depend on the source device/app that recorded the data
  • Not all devices track detailed sleep stages

Duplicate sleep sessions​

Some devices may record overlapping sessions. Filter by source:

const sessions = await HealthX.sleep.getSessions({ ... });

// Group by date and take the longest session per night
const uniqueSessions = sessions.reduce((acc, session) => {
  const date = session.startTime.split('T')[0];
  if (!acc[date] || session.duration > acc[date].duration) {
    acc[date] = session;
  }
  return acc;
}, {} as Record<string, SleepSession>);

Duration doesn't match sum of stages​

The total duration is calculated from startTime to endTime. Stage durations may not cover the entire period (gaps between stages, untracked time, etc.).

Build Issues​

Android: "SDK location not found"​

Create android/local.properties:

sdk.dir=/Users/YOUR_USERNAME/Library/Android/sdk

iOS: "Signing requires a development team"​

  1. Open ios/YourApp.xcworkspace in Xcode
  2. Select your project
  3. Go to Signing & Capabilities
  4. Select your team

Expo: EAS Build fails​

Check that the config plugin is properly configured:

{
  "expo": {
    "plugins": [
      ["react-native-healthx", {}]
    ]
  }
}

Still Having Issues?​

  1. Check the GitHub Issues
  2. Search for similar problems
  3. If not found, create a new issue with:
    • Platform (iOS/Android)
    • React Native version
    • Expo version (if applicable)
    • Device/emulator details
    • Minimal reproduction steps