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.
The log surface
Section titled “The log surface”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.
| Method | What 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.shared.setLogLevel(.debug)Beekon.shared.log(.info, "user tapped 'start trip'")
Task { for await e in await Beekon.shared.logs { print("[\(e.level)] \(e.category): \(e.message)") }}
let entries = try await Beekon.shared.getLog(from: hourAgo, to: Date())let ndjsonPath = try await Beekon.shared.exportLog()await Beekon.instance.setLogLevel(LogLevel.debug);await Beekon.instance.log(LogLevel.info, "user tapped 'start trip'");
Beekon.instance.logs.listen((e) { print('[${e.level}] ${e.category}: ${e.message}');});
final entries = await Beekon.instance.getLog( from: DateTime.now().subtract(const Duration(hours: 1)), to: DateTime.now(),);final ndjsonPath = await Beekon.instance.exportLog();await Beekon.setLogLevel('debug');await Beekon.log('info', "user tapped 'start trip'");
Beekon.onLog((e) => console.log(`[${e.level}] ${e.category}: ${e.message}`));
const entries = await Beekon.getLog( new Date(Date.now() - 3_600_000), new Date(),);const ndjsonPath = await Beekon.exportLog();The error taxonomy
Section titled “The error taxonomy”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:
| Call | Throws on |
|---|---|
getLocations, deleteLocations | a storage failure |
addGeofences | an invalid geofence; GeofencesManagedByServer in Cloud mode |
removeGeofences | GeofencesManagedByServer in Cloud mode |
getCurrentLocation | location unavailable |
configure, the cloud factory | an invalid configuration |
setUserId | an invalid user id |
pendingUploadCount, getLog, exportLog, clearLog | a 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 BeekonExceptionwith five subclasses:StorageException(cause),InvalidConfiguration(reason),InvalidGeofence(reason),GeofencesManagedByServer,LocationUnavailable(reason). An invalid user id throws a plainIllegalArgumentException, not aBeekonException. - iOS:
enum BeekonError: Errorwith six cases:.invalidConfiguration(reason:),.invalidGeofence(reason:),.geofencesManagedByServer,.storage(reason:),.invalidUserId(reason:),.locationUnavailable(reason:). - Flutter:
sealed class BeekonExceptionwith seven subclasses:LocationUnavailable(reason),StorageException(reason),InvalidConfiguration(reason),InvalidGeofence(reason),GeofencesManagedByServer,NoActivity,InvalidUserId(reason).NoActivityis Android-only:requestPermissionoropenSettingswas called while the plugin had no foreground Activity. - React Native:
class BeekonError extends Errorwith akindfield:'storage','invalidGeofence','geofencesManagedByServer','invalidConfiguration','invalidUserId','permissionDenied','locationServicesDisabled','locationUnavailable'. The last three aregetCurrentLocation()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.
Thrown vs. Stopped
Section titled “Thrown vs. Stopped”| Scenario | Surface |
|---|---|
The user never granted permission and you call start() | start() returns; state becomes Stopped(PermissionDenied). No exception. |
| The user revokes permission while tracking | State becomes Stopped(PermissionDenied). No exception. |
| Android stops the foreground service under memory pressure | State becomes Stopped(System). Android only. |
getLocations(...) hits a SQLite failure | throws BeekonException.StorageException / BeekonError.storage |
addGeofences(...) given an invalid geofence | throws BeekonException.InvalidGeofence / BeekonError.invalidGeofence |
A cloud config with an empty or cell-less project key, or a rejected endpoint | throws BeekonException.InvalidConfiguration / BeekonError.invalidConfiguration |
configure(...) switching to cloud mode while tracking | throws 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.
Troubleshooting
Section titled “Troubleshooting”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() seems to do nothing
Section titled “start() seems to do nothing”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.
Locations are sparse or never arrive
Section titled “Locations are sparse or never arrive”- The gate is too tight. A fix is stored only when both
minTimeBetweenLocationsSecondsandminDistanceBetweenLocationsMetershave passed.accuracyMode: lowalso raises the distance gate to at least 500 m. Lower the values, or set one to0to 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.
Sync keeps failing
Section titled “Sync keeps failing”- Wrong status code. The SDK deletes the batch on
2xx, and also on400and422, which mean the payload will never be accepted. Any other4xxyou didn’t intend (for example a framework’s404for an unmatched route) keeps the batch, and the queue looks stuck. Check that your route returns2xx. - Locations go missing. If your server answers
400or422to good data, the SDK deletes that batch and doesn’t retry, andsyncStatusshows Failed with reasonrejected. Return400or422only for a payload that will never be accepted. - A redirect. Beekon refuses
3xxand treats it as permanent. Serve the exacturldirectly, with no301or302. - The body isn’t gunzipped. The body is always
Content-Encoding: gzip. A server that passes the raw bytes to a JSON parser fails with400, and the SDK then deletes the batch. Gunzip first. - Auth. A
401or403shows as a sync auth failure. WithSyncConfig.authset, the SDK refreshes the token and retries. With staticheaders, callconfigure()again with new ones. See Auth & token refresh. - Watch
syncStatusandpendingUploadCount()to see whether the queue is going down.
Geofences don’t fire
Section titled “Geofences don’t fire”- 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_NOTIFICATIONSon Android 13 and later, and notification authorisation on iOS. Ask withrequestPermission(notifications)before relying on crossing alerts. - Subscribe to
geofenceEventsto 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()fromApplication.onCreate. Reboots and app updates are covered by the SDK’s boot receiver, which needsACCESS_BACKGROUND_LOCATIONto 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 inmain(). - 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()fromApplication.onCreate.
Android: tracking stops on some devices
Section titled “Android: tracking stops on some devices”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.