Skip to main content

Troubleshooting

Start every investigation with a status snapshot. It is synchronous and cheap:

console.log(JSON.stringify(LocationTracker.getStatus(), null, 2));

Errors in message start with a stable [code] prefix that you can match on in code.

Status codes​

CodeMeaningFix
[eval_release_blocked]You are running a release build of the Evaluation edition. buildTier is 'release'.Run a debug build, or get a license.
[permission_denied]Location permission is missing or was revoked, so tracking did not start or has stopped.Call requestLocationPermission(true), then startTracking() again.
[foreground_denied]Android refused to start the location foreground service, usually because tracking was started while the app was in the background.Call startTracking() while the app is visible.
[start_failed]The pipeline could not start (Android). The rest of the message says why.Check permissions and Google Play services, then retry.
[not_running]syncNow() was called while tracking is stopped.Call startTracking() first. Pending points sync once tracking runs.
[sync_rejected]Your server returned a non-retryable HTTP status.Check your endpoint against the backend contract.
[invalid_profile]setTrackingProfile() received an unknown value.Use one of the TrackingProfile values.

Common problems​

Nothing happens when I call startTracking()​

  1. Is buildTier 'release'? The Evaluation edition only tracks in debug builds.
  2. Is authorization 'denied' or 'notDetermined'? Request permission first.
  3. On Android 13 or newer, did the user deny notifications? The foreground notification is required for background tracking. See Android setup.

Points appear in the app but never reach my server​

  • Check online, pending and lastSyncError in getStatus().
  • http_404: the tracker posts to {serverUrl}/api/location/track. Pass the base URL to startTracking(), not the full endpoint.
  • Plain http:// is blocked by default on both platforms. Use HTTPS, or add the cleartext exceptions from the Android and iOS setup pages.
  • On a physical device, localhost is the phone itself. Use your computer's LAN IP or a tunnel.

Tracking stops after the app is swiped away (Android)​

  • The user may have force-stopped the app from system settings. That is not recoverable until the app is opened again. See Android force-stop.
  • Some vendors (Xiaomi, Huawei, OnePlus, Oppo, Vivo, Samsung) kill background apps aggressively. Call requestIgnoreBatteryOptimizations() and point users to dontkillmyapp.com for vendor-specific settings.
  • Check exactAlarmsAllowed. If it is false, call openExactAlarmSettings() so recovery can be scheduled reliably.

Tracking stops in the background (iOS)​

  • authorization must be 'always' for relaunch after the app is killed and after reboot. 'whenInUse' only tracks while the app is open or recently backgrounded.
  • Check exactAlarmsAllowed (on iOS this means Background App Refresh is available) and batteryUnrestricted (Low Power Mode is off).
  • Confirm UIBackgroundModes contains location and fetch in Info.plist. See iOS setup.

Points are sparse while I am standing still​

That is the adaptive_low_power profile parking GPS while motionState is stationary. It wakes when you move. Use balanced or continuous_fitness if you need steady points. See TrackingProfile.

Coordinates are rough or jump around​

  • iOS: check preciseLocation. If it is false, the user turned off Precise Location and points are approximate.
  • Android: the user may have granted only approximate location. Request fine location again.
  • Indoors, GPS accuracy is poor. Check accuracy on each LocationEvent.

rejected keeps growing​

Your server returns 4xx for those batches. Read lastSyncError, fix the endpoint, and set maxAttempts to 0 with setSyncPolicy() if you never want to dead-letter.

Build errors​

  • "TurboModuleRegistry.getEnforcing(...): 'LocationTracker' could not be found": the New Architecture is disabled, or the native build is stale. Enable the New Architecture, run pod install, and rebuild the app (a Metro reload is not enough).
  • iOS: undefined symbols or framework not found: run cd ios && pod deintegrate && pod install, then clean the build folder in Xcode.
  • Android: duplicate class or manifest merge errors: run cd android && ./gradlew clean, and make sure no other library declares a conflicting foreground service type.

Still stuck?​

Open an issue at GitHub issues, or email punithm300@gmail.com. Include:

  • The output of getStatus().
  • Platform, OS version and device model.
  • React Native version, and whether it is a debug or release build.
  • What you expected and what happened.