Troubleshooting

Common issues and their solutions. Most problems are related to permissions, battery optimization, or platform-specific behavior.

GPS not updating in the background (iOS)

iOS

Ensure the "Location updates" background mode is enabled in Xcode (Signing & Capabilities). Verify Info.plist contains NSLocationAlwaysAndWhenInUseUsageDescription. Check that the user granted "Always" permission — "While Using" is not sufficient for background updates.

GPS not updating in the background (Android)

Android

The plugin uses a Foreground Service with a persistent notification. Ensure POST_NOTIFICATIONS permission is granted on Android 13+. Some OEMs (Xiaomi, Huawei, Samsung) aggressively kill background services — see the battery optimization section below.

OEM battery optimization kills service

Android

Many Android OEMs add proprietary battery optimization that kills foreground services. Use checkBatteryOptimization() and requestBatteryOptimization() to detect and prompt users. Listen for onBatteryWarning events. Direct users to Settings > Apps > [Your App] > Battery > Unrestricted. See dontkillmyapp.com for device-specific instructions.

iOS shows approximate location only

iOS

iOS 14+ allows users to grant only approximate (±5km) location. The plugin detects this and fires onAccuracyWarning. Guide users: Settings > Privacy > Location Services > [Your App] > Precise Location: ON.

Foreground notification won't go away

Android

On Android, the notification is required by the OS for foreground services. It disappears automatically when you call stop(). If it persists after an app crash, restart the app and call stop() or clear the app from recent tasks.

Trial session won't start (cooldown active)

iOS, Android

After a 30-minute trial session ends, there's a 1-hour cooldown before the next one. The plugin throws TRIAL_COOLDOWN if you call start() during this period. Wait for the cooldown to expire or add a license key.

HTTP POST requests failing

iOS, Android

Check onHttp event for statusCode and error details. Verify the URL is reachable from a device (not just localhost). Ensure your server accepts the POST body format (JSON with location/coords keys). Failed requests are buffered automatically and retried on next location update.

Geofence events not triggering

iOS, Android

Geofencing depends on the device's geofencing hardware (Wi-Fi, cell towers, GPS). Small radius (<100m) may not trigger reliably on all devices. Ensure configure() was called before addGeofence(). Check that notifyOnEntry/notifyOnExit is set to true. On Android, background location permission is required.

Location accuracy is poor

iOS, Android

Use desiredAccuracy: "high" for GPS-level accuracy. Test on a physical device — simulators use fake locations. Ensure the device has a clear sky view for GPS signal. Indoor testing typically shows lower accuracy.

Plugin works in dev but not in production build

iOS, Android

Verify the license key is included in the production config. Check that bundle ID in the license matches the built app. Run configure() and check the ConfigureResult for licenseError. Ensure native build includes all required permissions and entitlements.

Battery Optimization Detection

Use the plugin API to detect and prompt users about battery optimization:

// Check battery optimization state
const status = await checkBatteryOptimization();

if (status.isIgnoringOptimizations === false) {
  // Show explanation, then open settings
  await requestBatteryOptimization();
}

// Listen for ongoing warnings
addListener('onBatteryWarning', (event) => {
  console.warn('Battery optimization active:', event.message);
});

Use Debug Mode for Diagnosis

Set debug: true in your configure options to get verbose native logs and JavaScript onDebug events. This is the fastest way to diagnose tracking issues. See the Debug Mode page for details.