Android WorkManager: Guaranteed Background Execution with Constraints

The problem and the useful answer

You need background work that must run even if the app exits or the device restarts, such as syncing data or uploading logs, without draining battery. WorkManager is the recommended Jetpack API for deferrable, guaranteed execution with constraint-based scheduling. It handles Doze, App Standby and manufacturer battery optimizations so the work runs when conditions are met.

Mechanism with one worked configuration

WorkManager separates what runs, a Worker subclass, from when it runs, a WorkRequest with constraints. The system decides exact timing.

1. Define the Worker

Extend Worker and override doWork(). The method runs on a background thread.

class UploadLogWorker(context: Context, params: WorkerParameters) : Worker(context, params) {
    override fun doWork(): Result {
        val logPath = inputData.getString("log_path") ?: return Result.failure()
        return try {
            // perform upload here
            Result.success()
        } catch (e: Exception) {
            Result.retry()
        }
    }
}

Result.success() marks complete. Result.retry() triggers exponential backoff. Result.failure() stops retries.

2. Build a OneTimeWorkRequest with constraints

val constraints = Constraints.Builder()
    .setRequiredNetworkType(NetworkType.CONNECTED)
    .setRequiresCharging(true)
    .setRequiresBatteryNotLow(true)
    .build()

val request = OneTimeWorkRequestBuilder<UploadLogWorker>()
    .setConstraints(constraints)
    .setInputData(workDataOf("log_path" to "/data/logs/app.log"))
    .setBackoffCriteria(BackoffPolicy.EXPONENTIAL, 15, TimeUnit.MINUTES)
    .build()

All constraints are ANDed. Work starts only when charging, network connected and battery not low.

3. Enqueue

WorkManager.getInstance(context).enqueue(request)

The request is persisted across process death and reboot.

Limits you cannot work around

• Minimum repeat interval is 15 minutes for PeriodicWorkRequest.
• Workers that run longer than about 10 minutes may be stopped by the system.
• WorkManager does not guarantee exact timing, only best-effort within constraints.
• No direct UI access. Observe WorkInfo via LiveData or Flow on the main thread.

Common mistakes

• Using WorkManager for immediate UI work. Use coroutines or Handler on the main thread for now actions.
• Forgetting the required dependency. Add implementation 'androidx.work:work-runtime-ktx:2.9.0' and sync Gradle.
• Not handling cancellation. Check isStopped in long loops to avoid wasted battery when constraints change.
• Assuming periodic work runs at exact intervals. The system batches work to save battery.

Verification

1. Add the dependency, sync, and enqueue the request.
2. Plug in charger and connect to Wi-Fi. Check adb logcat for WM- tags confirming enqueue and execution.
3. Unplug charger. Work should pause until constraints are satisfied again.

WorkManager is not suitable for high-frequency or real-time tasks. Use AlarmManager or a foreground service for those cases, and be aware some manufacturers apply additional battery optimizations that can delay work.