Skip to content

Diagnostics & troubleshooting

Background location is hard to debug: the events that matter happen after the app is backgrounded, while it’s terminated, or on someone else’s phone. This page covers the on-device log buffer, what Beekon throws and what it reports as a state, and a list of symptoms with fixes.

Beekon keeps an on-device log buffer that you can read, export and follow live, so you can see what the SDK did while the app was in the background. Logging never sends anything off the device.

MethodWhat it does
setLogLevel(level)Sets the lowest level that is recorded. Entries below it are discarded.
log(level, message)Writes your own entry into the SDK’s log, with category app.
getLog(from, to)Reads stored entries in a time range, oldest first.
exportLog()Writes the buffer to an NDJSON file and returns its path, ready to attach to a bug report.
clearLog()Deletes all stored entries.
logs (stream)Each entry as it is recorded. onLog in React Native.

A LogEntry is { id, timestamp, level, category, message }. category names the subsystem (location, sync, …), or app for entries you write. The levels, most to least severe, are error, warn, info, debug and verbose; off records nothing.

Beekon.setLogLevel(LogLevel.Debug)
Beekon.log(LogLevel.Info, "user tapped 'start trip'")
lifecycleScope.launch {
Beekon.logs.collect { e ->
Log.d("beekon", "[${e.level}] ${e.category}: ${e.message}")
}
}
val entries = Beekon.getLog(from = hourAgo, to = Instant.now())
val ndjsonPath = Beekon.exportLog()

Beekon’s errors are typed, and start() never throws. Missing permissions, disabled location services and the OS stopping the service arrive as Stopped(reason) on the state stream, not as exceptions. Only these calls throw:

CallThrows on
getLocations, deleteLocationsa storage failure
addGeofencesan invalid geofence; GeofencesManagedByServer in Cloud mode
removeGeofencesGeofencesManagedByServer in Cloud mode
getCurrentLocationlocation unavailable
configure, the cloud factoryan invalid configuration
setUserIdan invalid user id
pendingUploadCount, getLog, exportLog, clearLoga storage failure (on iOS they are throws, so call them with try)

Invalid user id. setUserId(...) trims the value, and a blank or null value clears the id without an error. It throws when the trimmed value contains a control character or is longer than 256 UTF-8 bytes. Each platform’s type for this error is in the list below.

The per-platform types:

  • Android: sealed class BeekonException with five subclasses: StorageException(cause), InvalidConfiguration(reason), InvalidGeofence(reason), GeofencesManagedByServer, LocationUnavailable(reason). An invalid user id throws a plain IllegalArgumentException, not a BeekonException.
  • iOS: enum BeekonError: Error with six cases: .invalidConfiguration(reason:), .invalidGeofence(reason:), .geofencesManagedByServer, .storage(reason:), .invalidUserId(reason:), .locationUnavailable(reason:).
  • Flutter: sealed class BeekonException with seven subclasses: LocationUnavailable(reason), StorageException(reason), InvalidConfiguration(reason), InvalidGeofence(reason), GeofencesManagedByServer, NoActivity, InvalidUserId(reason). NoActivity is Android-only: requestPermission or openSettings was called while the plugin had no foreground Activity.
  • React Native: class BeekonError extends Error with a kind field: 'storage', 'invalidGeofence', 'geofencesManagedByServer', 'invalidConfiguration', 'invalidUserId', 'permissionDenied', 'locationServicesDisabled', 'locationUnavailable'. The last three are getCurrentLocation() precondition failures.

LocationUnavailable(reason) carries a LocationUnavailableReason: PermissionDenied, LocationServicesDisabled or Unavailable, in the platform’s casing. React Native spells the same three as the kinds above. See One-shot fix.

ScenarioSurface
The user never granted permission and you call start()start() returns; state becomes Stopped(PermissionDenied). No exception.
The user revokes permission while trackingState becomes Stopped(PermissionDenied). No exception.
Android stops the foreground service under memory pressureState becomes Stopped(System). Android only.
getLocations(...) hits a SQLite failurethrows BeekonException.StorageException / BeekonError.storage
addGeofences(...) given an invalid geofencethrows BeekonException.InvalidGeofence / BeekonError.invalidGeofence
A cloud config with an empty or cell-less project key, or a rejected endpointthrows BeekonException.InvalidConfiguration / BeekonError.invalidConfiguration
configure(...) switching to cloud mode while trackingthrows InvalidConfiguration. Call stop() first.
configure(...) given an out-of-range tracking value (for example a stationary radius outside 5–1000 m)No error. The value is clamped.

There is no NotInitialised or NotConfigured error. start() without an earlier configure(...) uses the last stored config, or the defaults on a fresh install.

Watch the state stream for everything to do with starting and stopping, and keep try/catch for history and geofence calls. Beekon doesn’t restart by itself after a stop: call start() again once the cause is fixed.

Each entry gives a symptom, the likely cause and the fix. Most problems come from permissions, the gate or the app’s own setup.

start() never throws. If tracking can’t run, state becomes Stopped(reason). Watch state and read the reason: permissionDenied, locationServicesDisabled, locationUnavailable, system, or backgroundStartDenied (in practice Android 12 and later only). user means stop() was called. Every platform defines all six. See Lifecycle & states.

  • The gate is too tight. A fix is stored only when both minTimeBetweenLocationsSeconds and minDistanceBetweenLocationsMeters have passed. accuracyMode: low also raises the distance gate to at least 500 m. Lower the values, or set one to 0 to turn that gate off. See Configuration.
  • No background permission. With only a foreground grant, tracking doesn’t resume after the OS stops the app or the device reboots, and geofences don’t fire, until the user opens the app again. Request background location (Always on iOS) with requestPermission(backgroundLocation): requestNextNeededPermission() asks only for required permissions and never for this one. See Requesting permissions.
  • iOS asks in two steps. iOS grants When in Use first; you then request Always. See Platform setup.
  • Wrong status code. The SDK deletes the batch on 2xx, and also on 400 and 422, which mean the payload will never be accepted. Any other 4xx you didn’t intend (for example a framework’s 404 for an unmatched route) keeps the batch, and the queue looks stuck. Check that your route returns 2xx.
  • Locations go missing. If your server answers 400 or 422 to good data, the SDK deletes that batch and doesn’t retry, and syncStatus shows Failed with reason rejected. Return 400 or 422 only for a payload that will never be accepted.
  • A redirect. Beekon refuses 3xx and treats it as permanent. Serve the exact url directly, with no 301 or 302.
  • The body isn’t gunzipped. The body is always Content-Encoding: gzip. A server that passes the raw bytes to a JSON parser fails with 400, and the SDK then deletes the batch. Gunzip first.
  • Auth. A 401 or 403 shows as a sync auth failure. With SyncConfig.auth set, the SDK refreshes the token and retries. With static headers, call configure() again with new ones. See Auth & token refresh.
  • Watch syncStatus and pendingUploadCount() to see whether the queue is going down.
  • Radius too small. Use 100 m or more. Smaller geofences are unreliable on real hardware.
  • Background location not granted. Geofence monitoring needs the same background grant (Always on iOS) as background tracking.
  • Notifications. Per-geofence notifications need POST_NOTIFICATIONS on Android 13 and later, and notification authorisation on iOS. Ask with requestPermission(notifications) before relying on crossing alerts.
  • Subscribe to geofenceEvents to check that crossings are recorded. See Geofencing.

Tracking doesn’t resume after the app is killed

Section titled “Tracking doesn’t resume after the app is killed”
  • Android: wire up cold-launch resume. Call Beekon.resumeIfNeeded() from Application.onCreate. Reboots and app updates are covered by the SDK’s boot receiver, which needs ACCESS_BACKGROUND_LOCATION to restart tracking. See Cold-launch resume.
  • iOS: automatic, with one exception. A significant location change wakes the terminated app and Beekon calls resumeIfNeeded() itself. If the user force-quits the app, iOS stops these wakes until the app is next opened. This is an iOS rule.
  • Flutter: call await Beekon.instance.resumeIfNeeded() early in main().
  • React Native: call await Beekon.resumeIfNeeded() early in your app entry.
  • Flutter and React Native on Android: a background relaunch may not start the Dart or JS engine. To resume in that case too, also call the native Beekon.resumeIfNeeded() from Application.onCreate.

Some manufacturers’ battery managers (Xiaomi, Oppo, Huawei, …) stop background services even when they run as foreground services. The SDK can’t prevent this; ask users to exempt your app. dontkillmyapp.com has steps for each vendor.

React Native: module is undefined / build fails

Section titled “React Native: module is undefined / build fails”

@wayq/beekon-rn requires the New Architecture (RN 0.76 or later). On the old architecture the TurboModule doesn’t link. Turn on the New Architecture in your app.