[Bug]: addGeofence() in headless mode on Android reports success but OS Geofencer does not actively monitor the registration

[johnswarbrick]

Required Reading

• Confirmed

Plugin Version

5.0.5

Flutter Doctor

[✓] Flutter (Channel stable, 3.41.2, on macOS 26.3 25D125 darwin-arm64, locale en-GB)
[✓] Android toolchain - develop for Android devices (Android SDK version 36.1.0)
[✓] Xcode - develop for iOS and macOS (Xcode 26.3)
[✓] Chrome - develop for the web
[✓] Connected device (3 available)
[✓] Network resources

• No issues found!

Mobile operating-system(s)

• iOS
• Android

Device Manufacturer(s) and Model(s)

Google Pixel 8

Device operating-systems(s)

Android 16

What happened?

Expected Behavior

When addGeofence() is called from a headless task (app terminated), the newly registered geofence should be actively monitored by the Android OS Geofencer, and EXIT events should fire when the device leaves the geofence radius.

Actual Behavior

addGeofence() succeeds (returns without error, plugin logs ✅ SEEKERAPP_FINE) but the Android OS Geofencer logs "registration not active, registration not permitted" for the newly added geofence. The geofence is not actively monitored — EXIT events do not fire until the OS Geofencer's low-power batch evaluation eventually picks them up (~2–7 minutes later).

This creates a significant gap in geofence tracking reliability when the app is terminated.

Steps to Reproduce

1. Configure plugin with stopOnTerminate: false, enableHeadless: true, geofenceModeHighAccuracy: false
2. Start monitoring with startGeofences()
3. Register initial geofences with addGeofence()
4. Terminate the app (swipe kill)
5. Move the device to trigger a geofence EXIT event
6. In the headless task handler, call addGeofence() to register a new geofence at the updated location
7. Continue moving — observe that EXIT events for the newly registered geofence are significantly delayed or missing

Debug Logs

Relevant logcat excerpts showing the issue:

Foreground geofences work correctly

16:26:13.717 TSLocationManager: ✅ SEEKERAPP_COARSE
16:26:13.718 TSLocationManager: ✅ SEEKERAPP_FINE
16:26:13.762 GeofenceProxy: Batched PI received for ...

After foreground addGeofence(), the OS Geofencer immediately shows "Batched PI received" confirming active monitoring.

App terminated, headless addGeofence() — OS rejects registration

16:27:14.504 TSLocationManager: ║ Geofencing Event: EXIT
16:27:14.504 TSLocationManager: ╟─ SEEKERAPP_FINE
16:27:58.508 [GeofenceHeadless] geofence EXIT: SEEKERAPP_FINE
16:27:59.065 TSLocationManager: ✅ SEEKERAPP_FINE   <-- addGeofence() reports success

16:28:00.017 GeofenceProxy: registration not active, registration not permitted.
16:28:00.017 GeofenceProxy: Batched PI received for ...   <-- note: this is evaluation of OLD registration

After headless addGeofence():

• Plugin reports success (✅)
• OS Geofencer logs "registration not active, registration not permitted"
• No EXIT events fire for 7+ minutes until the OS Geofencer's low-power sweep picks up the registration

7-minute blackout period

16:28:00.017  Last "Batched PI" evaluation
...
16:35:02.024  Next "Batched PI" evaluation  (7 minutes later)

During this gap, the device continued moving through multiple geofence boundaries, but no EXIT events fired.

Root Cause Analysis

The issue appears to be that addGeofence() in headless mode updates the plugin's internal geofence state and calls the platform GeofencingClient.addGeofences() API, but the Android OS Geofencer does not honour the registration because the app's monitoring adapter is not in an "active" state.

The key evidence is the OS Geofencer log: "registration not active, registration not permitted". This indicates the OS acknowledges the addGeofences() API call but does not activate monitoring for it. The plugin, however, reports success because the API call itself did not throw an error.

Why startGeofences() cannot be called in headless mode

We initially tried calling startGeofences() after addGeofence() in the headless handler. However:

1. startGeofences() internally calls stop() then start() (or equivalent)
2. In headless mode, stop() kills the existing foreground monitoring session
3. startGeofences() then fails with ForegroundServiceStartNotAllowedException on Android 12+ because background-launched processes cannot start foreground services
4. Result: monitoring is permanently dead until the user opens the app

Our current workaround

We now call startGeofences() without stop() first:

// After addGeofence() in headless handler:
try {
  await bg.BackgroundGeolocation.startGeofences();
} catch (e) {
  // Expected on Android 12+ in headless mode.
  // No stop() was called, so existing monitoring is preserved.
}

This sometimes succeeds in refreshing the monitoring adapter. When it fails, the existing monitoring state is preserved (since we didn't call stop()). We also use the heartbeat callback as a fallback to detect and correct missed geofence transitions.

Suggested Fix

The plugin should detect when addGeofence() is called in headless mode and either:

1. Automatically refresh the monitoring adapter after addGeofence() without a full stop/start cycle (similar to our workaround above)
2. Return a warning or different status when the OS reports "registration not active" so callers know the geofence may not be actively monitored
3. Document the limitation that addGeofence() in headless mode may not result in active monitoring on Android 12+

Context

We are building a location-aware mobile app that uses adjacent cells for geofencing. When a user exits one cell, we register a geofence for the new cell. This works perfectly in foreground/background but breaks when the app is terminated because the headless addGeofence() calls don't result in active OS monitoring.

The heartbeat callback (60s interval) serves as our fallback for detecting missed transitions, but the 7-minute blackout period after headless geofence registration significantly degrades the user experience.

Plugin Code and/or Config

bg.BackgroundGeolocation.ready(bg.Config(
  desiredAccuracy: bg.Config.DESIRED_ACCURACY_HIGH,
  distanceFilter: 0,
  stopOnTerminate: false,
  enableHeadless: true,
  startOnBoot: true,
  heartbeatInterval: 60,
  preventSuspend: true,
  geofenceModeHighAccuracy: false,
  foregroundService: true,
));

bg.BackgroundGeolocation.startGeofences();

Relevant log output

See main report

[johnswarbrick]

Update:

After further drive testing (25 km/h constant speed, 25 minutes, app terminated, Google Pixel 8, Android 16), we've identified a much more specific pattern than originally reported.

Key finding: headless addGeofence() works but degrades with each successive EXIT→addGeofence cycle

The original report stated that addGeofence() in headless mode is not actively monitored. Further testing reveals it does work-but only for 1-2 transitions before the OS stops honouring new registrations. A non-geofence plugin event (e.g. HEARTBEAT) resets the chain.

Observed pattern

We use a 180-second heartbeat interval. Each heartbeat that detects a cell mismatch calls addGeofence() to register a new geofence at the corrected position. When a geofence EXIT fires, the headless handler also calls addGeofence() for the next cell.

The pattern across every heartbeat-initiated chain in a 25-minute test:

Geofence source	ENTER fires?	EXIT fires?	Success rate
Heartbeat → addGeofence()	Yes, within 1-4s	Yes, within 20-35s	100% (6/6)
1st EXIT handler → addGeofence()	Yes, within 5s	Yes, within 20-55s	86% (6/7)
2nd EXIT handler → addGeofence()	Almost never	-	14% (1/7)
3rd EXIT handler → addGeofence()	Never	-	0% (0/1)

Every chain follows the same lifecycle:

1. Heartbeat fires → calls addGeofence() → OS activates monitoring → ENTER fires → EXIT fires
2. EXIT handler calls addGeofence() → usually works once more → EXIT fires
3. EXIT handler calls addGeofence() again → OS stops monitoring → silence until next heartbeat

Detailed trace from a single chain

19:28:02.568  [Heartbeat] addGeofence(P9_NEW_CELL)         ← heartbeat creates geofence
19:28:02.884  Geofencer: registration not active            ← OS warning (appears every time)
19:28:06.578  Geofencing Event: ENTER SEEKERAPP_FINE          ← OS activates monitoring (4s)
19:28:26.569  Geofencing Event: EXIT SEEKERAPP_FINE           ← EXIT fires (24s after ENTER)
19:28:26.610  [GeofenceHeadless] geofence EXIT               ← handler calls addGeofence()
19:28:26.981  Geofencer: registration not active             ← OS warning again
19:28:31.564  Geofencing Event: ENTER SEEKERAPP_FINE          ← OS activates (5s)-1st handler geofence works
19:29:11.558  Geofencing Event: EXIT SEEKERAPP_FINE           ← EXIT fires (45s)
19:29:11.601  [GeofenceHeadless] geofence EXIT               ← handler calls addGeofence() again
              Geofencer: registration not active             ← OS warning
              ... silence-no ENTER, no EXIT ...            ← 2nd handler geofence NOT monitored
19:32:02.328  [Heartbeat] detects mismatch, corrects         ← heartbeat resets the chain

This exact pattern repeats for all 6 heartbeat-initiated chains in the test.

Why the heartbeat resets the chain

The heartbeat fires as a HEARTBEAT plugin event, not a GEOFENCE event. The plugin is in a different internal state when dispatching a heartbeat vs processing a geofence EXIT. The heartbeat's addGeofence() call appears to happen outside the plugin's geofence event processing pipeline, which resets whatever state is degrading.

Critically, "registration not active, registration not permitted" appears for all headless addGeofence() calls-including the heartbeat-created ones that work perfectly. The warning alone does not predict whether monitoring will actually activate.

What this suggests about the root cause

This is not a simple "headless addGeofence doesn't work" issue. The degradation pattern suggests one of:

1. OS rate-limiting geofence re-registration from background processes-Android accepts the first 1-2 rapid successive GeofencingClient.addGeofences() calls but deprioritises subsequent ones within the same batch evaluation cycle

2. Plugin-internal state accumulation-each EXIT→addGeofence cycle creates new registration state (PendingIntent, GeofencingClient session). In foreground the plugin properly cleans up between cycles, but in headless mode the cleanup may be incomplete, causing the OS to stop honouring new registrations after 1-2 cycles

3. Batched PI scheduling disruption-rapid re-registrations within the same Batched PI cycle may cause the OS Geofencer to merge or skip evaluations, with each successive registration less likely to trigger a fresh evaluation

Additional observation: OS delivers heartbeat late

The heartbeat is configured at 180 seconds, but Android consistently delivers it at 240 seconds in headless mode (60s late), likely due to Doze/battery optimisation batching:

19:16:02  HEARTBEAT fired → scheduled next in 180000ms (should fire 19:19:02)
19:20:02  HEARTBEAT fired → 240s actual interval, 60s late
19:24:02  HEARTBEAT fired → 240s actual interval, 60s late
(pattern repeats exactly for all 6 heartbeats)

Test environment

• Plugin version: 5.0.5
• Platform: Android 16
• Device: Google Pixel 8 (real device, not emulator)
• Flutter: 3.27.4, Dart 3.6.2
• Config: stopOnTerminate: false, enableHeadless: true, startOnBoot: true, heartbeatInterval: 180, foregroundService: true, geofenceModeHighAccuracy: false
• Test: 25 km/h constant speed, 25 minutes continuous driving, app terminated (swipe kill)

Our current mitigation

We use a 60-second heartbeat that reads the cached fused location (no GPS radio cost) and calls addGeofence() when it detects a cell mismatch. This keeps each EXIT→addGeofence chain to 1 iteration, staying within the range where the OS reliably monitors. This gives ~90% real-time detection rate at driving speeds, with the remaining ~10% caught by the next heartbeat within 60 seconds.

[christocracy]

Thanks for the detailed report and logs — they were very helpful.

After reviewing the behavior and the plugin implementation, I don’t believe Android is actually rejecting the geofence registration in headless mode. What’s happening instead is a timing issue in the plugin’s internal evaluation pipeline.

When addGeofence() is called, the plugin does not immediately call GeofencingClient.addGeofences(). The flow is roughly:

addGeofence()
  → persist geofence to SQLite
  → reEvaluate()
  → evaluation buffer timer
  → EvaluationTask
       → GeofencingClient.addGeofences()

The important detail is that the actual OS registration only occurs inside EvaluationTask.

Previously, the evaluation pipeline always attempted to fetch a last known location before running evaluation. On modern Android versions (12+), obtaining location while the app is terminated/headless can be delayed or denied by the OS. When that happens, evaluation is postponed until the next location update arrives, which can be several minutes later.

This can create the exact symptom you observed:
• addGeofence() reports success (the record was stored)
• the OS is not yet actively monitoring it
• monitoring becomes active later when a location update eventually arrives

So the issue is not that Android refuses geofence registration in headless mode — it’s that the plugin’s evaluation step could be delayed while waiting for a background location.

I’ve pushed a fix that removes this dependency when the number of geofences is below Android’s limit (100). In that case the plugin now evaluates immediately without requiring a fresh location, since proximity selection is not needed.

In other words, geofence activation should now occur immediately after addGeofence() even when running in a headless task.

If you’re able to test the next snapshot build, I’d appreciate confirmation that this resolves the delayed activation you were seeing:

android/build.gradle

allprojects {
    ...
    repositories {
        // background_geolocation
        // [DEV] Sonatype SNAPSHOT url
        maven(url = "https://central.sonatype.com/repository/maven-snapshots/")
        ...               
    }
}

cd android
./gradlew app:dependencies | grep tslocationmanager
|    +--- com.transistorsoft:tslocationmanager:4.0.+ -> 4.0.22-SNAPSHOT

When you see 4.0.22-SNAPSHOT, go test.

[johnswarbrick]

Thanks for the quick fix and detailed explanation, @christocracy - really appreciated!

I've tested 4.0.22-SNAPSHOT with a constant 20 km/h simulated drive test.

4.0.22-SNAPSHOT has resolved the plugin-side evaluation delay - addGeofence() now reaches GeofencingClient.addGeofences() promptly - this is a great improvement from before.

However,the OS-side monitoring delay remains. Geofences registered in headless mode are accepted by the OS but not actively evaluated until the next location activity.

Every headless addGeofence() call — whether from the EXIT handler or the heartbeat — produces the same OS warning:

Geofencer: registration not active, registration not permitted for registration:
  10505/com.seekerapp.seekerapp.d4fd7e00 {na} (FINE)
  GeofenceRequest(53.987197,-1.508415+194.598m, ...)

This same warning also appears during foreground setup (where geofences work immediately), so the warning alone doesn't predict failure. The difference seems to be whether the OS has active location consumers at the time — in foreground, the GPS radio was recently active; in headless, it's idle.

Interpretation

Your fix successfully removed the plugin's internal dependency on a background location fetch before evaluation. The addGeofence() → EvaluationTask → GeofencingClient.addGeofences() path now completes immediately (I can see the geofence registration and geofenceschange events firing promptly in the logs).

But the OS layer appears to behave differently:

1. Foreground/active GPS: addGeofences() → OS evaluates immediately → ENTER/EXIT fires within seconds
2. Headless/idle GPS: addGeofences() → OS accepts registration → geofence sits unevaluated until the next location activity (e.g. heartbeat, another app using GPS)

Question

Is there anything the plugin could do at the GeofencingClient level to encourage immediate evaluation? For example:

• Requesting a single fused location update after addGeofences() to trigger evaluation
• Using geofenceModeHighAccuracy selectively for the first evaluation cycle
• Any undocumented Play Services API that forces geofence re-evaluation

Happy to run additional tests if useful.

Setup

• Plugin version: TSLocationManager version: 4.0.22-SNAPSHOT (4047) (confirmed in logs)
• Heartbeat: 300s (deliberately set high to isolate geofence EXIT behaviour)
• Geofence count: Maximum 2 (well below the 100 threshold)
• Mode: startGeofences() (geofence-only, no location tracking)
• App state: Terminated/headless after initial setup

[christocracy]

Requesting a single fused location update after addGeofences() to trigger evaluation

Android is now very strict about when location can be requested in the background / headless. It will often simply refuse to provide a location unless the app was awakened due to:

• MotionActivity api event
• Geofencing event.
• device reboot

You say you're using heartbeat: you're free to call .getCurrentPosition yourself. I think you'll find that Android often fails to provide a location when your app is terminated / in bg for longer than about 30s.

[christocracy]

Is this device in-motion while you're testing? If you're sitting stationary at your desk, geofence events are often delayed. It helps to simulate movement by shaking your device vigorously. I know that the native Android Geofencing API uses the motion API internally.

[johnswarbrick]

Hi @christocracy -

I've been doing incremental version testing and managed to pin down the issue between 4.18.3 (works fine) and 5.0.0 (issue present)

Both 4.18.2 and 4.18.3 resolve to native 3.7.0 and chain perfectly — 15 consecutive headless EXITs at 25 km/h with zero failures.

The regression is in tslocationmanager 4.0.x.

When using 5.0.0 it appears that with geofenceInitialTriggerEntry: false and startGeofences() (geofence-only mode), tslocationmanager version 4.0.x suppresses all EXIT events with:

║ Ignoring spurious geofence EXIT (never entered)
╟─ id=SEEKERAPP_FINE
╟─ entryState=OUTSIDE

Since no ENTER event is ever fired (by design in our app we only monitor EXIT), the native library considers every EXIT "spurious" and drops it.

The chain degradation, heartbeat dependency, and evaluation latency issues I reported earlier were all just symptoms of this single root cause. With geofenceInitialTriggerEntry: true (trying to work around the suppression), the OS couldn't reliably deliver initial ENTER events in headless mode, causing chain degradation. With false on tslocationmanager` 3.7.0, everything works fine.

We're currently pinned to 4.18.3 to avoid the regression.

In terms of a solution, could the spurious exit detection be made configurable, or could it respect geofenceInitialTriggerEntry: false as a signal that EXIT-without-ENTER is expected?

As a side note, the snapshot fix (skipping the pre-registration location fetch when geofence count < 100) is still useful in principle - it makes addGeofence() reach the OS faster, which is objectively better. In our testing it didn't help because the spurious exit suppression was blocking everything downstream. If that suppression could be fixed as mentioned above, then the faster registration path would be a net positive, so the change is still valuable.

Plugin configuration

await BackgroundGeolocation.ready(Config(
  geofenceInitialTriggerEntry: false,
  geofenceModeHighAccuracy: false,
  disableLocationAuthorizationAlert: false,
  geofenceProximityRadius: 6150,
  disableMotionActivityUpdates: true,
  disableStopDetection: true,
  stopOnTerminate: false,
  startOnBoot: true,
  enableHeadless: true,
  heartbeatInterval: 3600,
));
await BackgroundGeolocation.startGeofences();

Geofences registered with:

BackgroundGeolocation.addGeofence(Geofence(
  identifier: 'SEEKERAPP_FINE',
  radius: 225,
  latitude: ...,
  longitude: ...,
  notifyOnEntry: false,
  notifyOnExit: true,
  notifyOnDwell: false,
));

I tried setting notifyOnEntry: true but it doesn't help because the OS doesn't fire ENTER for headless-registered geofences either. The suppression can only be fixed in the plugin by not requiring entry state for EXIT delivery.

Version Results

Plugin	Native lib	EXIT chain (headless, 25 km/h)	Suppression
4.18.2	tslocationmanager 3.7.0	15/15 — unlimited	None
4.18.3	tslocationmanager 3.7.0	15/15 — unlimited	None
5.0.0	tslocationmanager 4.0.21	0 — all suppressed	"never entered"
5.0.5	tslocationmanager 4.0.21	0 — all suppressed	"never entered"

[christocracy]

In terms of a solution, could the spurious exit detection be made configurable, or could it respect geofenceInitialTriggerEntry: false as a signal that EXIT-without-ENTER is expected?

Try latest 4.0.22-SNAPSHOT

[johnswarbrick]

Try latest 4.0.22-SNAPSHOT

I tried a fresh build using 4.0.22-SNAPSHOT just now but the same problem remains

[christocracy]

Try latest 4.0.22-SNAPSHOT (build 4048)

03-17 13:06:41.158  9533  9612 I TSLocationManager: ╔═════════════════════════════════════════════
03-17 13:06:41.158  9533  9612 I TSLocationManager: ║ TSLocationManager version: 4.0.22-SNAPSHOT (4048)
03-17 13:06:41.158  9533  9612 I TSLocationManager: ╠═════════════════════════════════════════════

[johnswarbrick]

Retested again with 4.0.22-SNAPSHOT (build 4048) with partial success.

The Ignoring spurious geofence EXIT (never entered) seems to be gone and the first EXIT now fires.

But the chain still breaks after the first headless re-registration.

The newly registered geofence never produces a subsequent EXIT event.

Note the device is within the geofence when it is created.

The sequence is:

1. Geofence created in foreground mode at application start
2. Application is terminated and headless service starts
3. EXIT event occurs and is delivered to headless handler
4. New geofence created in headless mode (addGeofence succeeds, geofenceschange fires)
5. No further EXIT events - device continued moving for 2+ minutes with no geofence activity

The same test on 4.18.3 (tslocationmanager 3.7.0) produces 15 consecutive headless EXIT→re-register cycles over 10 minutes with zero failures

[christocracy]

Try latest 4.0.22-SNAPSHOT (build 4049)

03-17 13:06:41.158 9533 9612 I TSLocationManager: ╔═════════════════════════════════════════════
03-17 13:06:41.158 9533 9612 I TSLocationManager: ║ TSLocationManager version: 4.0.22-SNAPSHOT (4049)
03-17 13:06:41.158 9533 9612 I TSLocationManager: ╠═════════════════════════════════════════════