Does Capacitor's BackgroundTask plugin preserve retry markers after process termination?

Question

I'm designing a retry mechanism for a Capacitor app that performs server writes through the @capacitor-community/http plugin. Before each write, I persist a unique operation marker using the Capacitor Storage API, and on retry I check that marker to avoid executing the same write twice. This works while the app stays alive.

The unresolved case is process termination: if the app is killed (or suspended by Android battery optimizations) while a retry is pending in a BackgroundTask, I cannot tell whether the Storage marker is guaranteed to have been flushed before the task is suspended, or whether the retry queue state survives a cold restart. If the marker is lost, the app could either skip a legitimate retry or issue a duplicate write on the next launch.

Assume Capacitor 6 with the official Storage and BackgroundTask plugins on Android and iOS.

Is the Storage write guaranteed to be durable before a BackgroundTask is suspended or the process is killed? What is the recommended pattern for reconciling a persisted retry marker against server state after a cold restart? Should deduplication rely on the client marker at all, or must the idempotency key be enforced entirely server-side?

Tasadduq Burney · Answer

Durability and Persistence Analysis
No, the BackgroundTask plugin does not preserve retry markers or queue states after process termination. It provides a temporary execution window to finish a current operation; it is not a persistent job scheduler. If the OS kills the process or the background window expires, any pending logic in the JavaScript heap is lost.

Storage Flush Guarantees
While the Capacitor Storage (Preferences) plugin utilizes native durable stores (SharedPreferences on Android and UserDefaults on iOS), there is no transactional guarantee that a write is physically flushed to disk before an abrupt process termination. Because the bridge between the JavaScript engine and the native layer is asynchronous, a process kill occurring immediately after a Storage.set() call may result in the marker never reaching the native disk layer.

Recommended Reconciliation Pattern
Since client-side markers cannot guarantee exactly-once delivery across cold restarts, you should shift the source of truth to the server. The recommended pattern is as follows:

Generate a Client-Side UUID: Create a unique idempotency key for the operation and persist it to Storage before attempting the write.
Include Key in Request: Send this UUID in a custom header (e.g., X-Idempotency-Key) with the server write.
Server-Side Enforcement: The server must track these keys for a defined TTL. If a duplicate key is received, the server returns the original successful response without re-executing the write.
Cold Restart Recovery: On app launch, scan Storage for any markers that were not cleared. Re-issue these requests using the same UUID. The server-side idempotency ensures that if the previous attempt actually succeeded before the crash, no duplicate data is created.

Verification Steps
To verify the failure point in your specific environment, use the following scoped test:

Trigger a BackgroundTask and initiate a Storage.set().
Immediately force-stop the application via Android Studio (Stop button) or Xcode.
Relaunch the app and check if the marker exists. If it is missing, you have confirmed the lack of atomic flushing during termination.

Diagnostic Detail Needed: Are you using the @capacitor/preferences plugin or a custom SQLite implementation? SQLite provides stronger ACID guarantees for markers than the key-value Preferences API.

Does Capacitor's BackgroundTask plugin preserve retry markers after process termination?

1 answer

Durability and Persistence Analysis

Storage Flush Guarantees

Recommended Reconciliation Pattern

Verification Steps

Your perspective belongs here.

0 question comments