2 posts tagged with "Kotlin coroutines"

Foreground services used to be the Swiss army knife for “do something now and don’t get killed.” Starting in Android 13 and tightened in 14–15 (and again in recent Android 17 previews), foreground services must declare and use the correct types, hold the right permissions, and start within strict timing windows. Many apps now crash with type mismatches, missing permissions, or background-start exceptions.

If your app still relies on foreground services for deferrable work (uploads, syncs, backups), the correct fix isn’t “pick the right type and pray.” It’s to migrate to WorkManager and only use foreground mode when it’s truly warranted. This post shows a practical, production-grade migration path you can drop into a real app.

Prerequisites​

• Android Studio Koala or newer
• Kotlin 1.9.20+ (Kotlin 2.x is fine)
• AGP 8.3+ (8.5+ recommended)
• compileSdk = 35 (Android 15), targetSdk = 35
• minSdk = 23+
• WorkManager 2.9.1

Gradle dependencies:

dependencies {
    implementation("androidx.work:work-runtime-ktx:2.9.1")
    implementation("androidx.core:core-ktx:1.13.1")
    implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.8.4")
    // Optional for Compose sample UI
    implementation("androidx.lifecycle:lifecycle-runtime-compose:2.8.4")
}

The real-world problem​

You might see one or more of these on Android 14+ or recent Android 17 builds:

• SecurityException: Missing required permission for foreground service type: FOREGROUND_SERVICE_DATA_SYNC
• java.lang.IllegalArgumentException: Service did not specify foregroundServiceType
• ForegroundServiceStartNotAllowedException: startForegroundService() not allowed while background
• AppNotResponding or kill due to late startForeground() call

These aren’t intermittent “OEM quirks.” They’re the platform telling you to stop using foreground services for deferrable, batchable work.

When to keep a Foreground Service (FGS) vs. migrate​

Keep a dedicated FGS only when the system says it’s the right tool:

• Media playback (mediaPlayback)
• Active navigation and continuous location/fitness tracking (location)
• Phone calls/VoIP (phoneCall)
• Screen capture/media projection (mediaProjection)
• Remote messaging and certain accessibility/system-exempted flows

Everything else (uploads, data sync, backups, log shipping, prefetch, long computations) should be WorkManager.

Target feature for migration: reliable photo upload with progress​

Scenario:

• User selects a batch of photos to upload.
• Work should respect constraints (unmetered network, device charging if desired).
• Show progress when user stays in-app; continue reliably across process death and device reboots.
• Comply with Android 14–17 foreground service restrictions.

We’ll migrate from a legacy FGS to WorkManager.

What the old code probably looks like (anti-pattern)​

Manifest:

<service
    android:name=".upload.UploadService"
    android:exported="false"
    android:foregroundServiceType="dataSync" />

Service:

class UploadService : Service() {
    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
        startForeground(NOTIFICATION_ID, buildNotification())
        // Long-running upload on a thread...
        // Crashes on 14+ if types/permissions mismatch or background-start happens.
        return START_NOT_STICKY
    }
}

Common failures:

• Missing uses-permission for the declared type.
• Background-start blocked on newer Android.
• Timing windows missed if uploads initialize slowly.
• The service outlives the app process and gets killed mid-upload.

The modern approach with WorkManager​

• Use Worker for deferrable uploads.
• Enter foreground mode only while needed using ForegroundInfo.
• Correctly declare the foreground service type and permission only if you actually run in foreground.
• Let WorkManager handle process death, retries, constraints, and OS quotas.

Step 1: Manifest cleanup​

Remove the legacy service declaration. Then add only the permissions you truly need.

If you plan to ever run the upload in foreground (e.g., immediate user-triggered large batch with visible progress), you must add the corresponding FGS permission for your chosen type on Android 14+.

For data sync uploads:

<uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" />

If you don’t plan to run in foreground mode at all, do not add FGS permissions or types.

For notifications on Android 13+:

<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

Create a notification channel at app startup:

fun ensureUploadChannel(context: Context) {
    if (Build.VERSION.SDK_INT >= 26) {
        val channel = NotificationChannel(
            "upload",
            "Uploads",
            NotificationManager.IMPORTANCE_LOW
        ).apply { description = "Background uploads" }
        context.getSystemService(NotificationManager::class.java).createNotificationChannel(channel)
    }
}

Step 2: Define the Worker​

We’ll implement a robust UploadWorker with:

• Constraints (e.g., unmetered network)
• Exponential backoff
• Foreground mode with correct type when needed
• Progress updates

class UploadWorker(
    appContext: Context,
    params: WorkerParameters,
    private val uploader: PhotoUploader, // Inject via DI; shown simplified
) : CoroutineWorker(appContext, params) {

    override suspend fun getForegroundInfo(): ForegroundInfo {
        // Only called if we entered foreground via setForeground()
        return buildForegroundInfo(progress = 0)
    }

    override suspend fun doWork(): Result {
        // Input: list of photo URIs
        val uris = inputData.getStringArray(KEY_URIS)?.toList().orEmpty()
        if (uris.isEmpty()) return Result.success()

        // Decide whether to use foreground mode for this run (e.g., user-initiated large batch)
        val needsImmediateUserVisible = inputData.getBoolean(KEY_USER_INITIATED, false)
        if (needsImmediateUserVisible) {
            setForeground(buildForegroundInfo(progress = 0))
        }

        try {
            var completed = 0
            for (uri in uris) {
                setProgress(workDataOf(KEY_PROGRESS to ((completed * 100) / uris.size)))
                uploader.upload(uri) // make it suspend, chunked, cancellable
                completed++
                if (needsImmediateUserVisible) {
                    setForeground(buildForegroundInfo(progress = ((completed * 100) / uris.size)))
                }
            }
            setProgress(workDataOf(KEY_PROGRESS to 100))
            return Result.success()
        } catch (e: IOException) {
            // Network/server issue: retry with backoff
            return Result.retry()
        } catch (e: CancellationException) {
            throw e // cooperatively cancel
        } catch (t: Throwable) {
            // Unexpected, don't loop forever
            return Result.failure()
        }
    }

    private fun buildForegroundInfo(progress: Int): ForegroundInfo {
        val notification = NotificationCompat.Builder(applicationContext, "upload")
            .setSmallIcon(R.drawable.ic_upload)
            .setContentTitle("Uploading photos")
            .setContentText("$progress%")
            .setOnlyAlertOnce(true)
            .setOngoing(true)
            .setProgress(100, progress, false)
            .build()

        // You must set the correct foreground service type on Android 14+ if you use foreground mode
        return ForegroundInfo(
            NOTIFICATION_ID,
            notification,
            ServiceInfo.FOREGROUND_SERVICE_TYPE_DATA_SYNC
        )
    }

    companion object {
        const val KEY_URIS = "uris"
        const val KEY_USER_INITIATED = "user_initiated"
        const val KEY_PROGRESS = "progress"
        const val NOTIFICATION_ID = 42
    }
}

WorkerFactory or Hilt can provide PhotoUploader; omitted for brevity.

Register the worker with WorkManager (if you use a custom WorkerFactory, wire it in your Configuration).

Step 3: Enqueue unique work with constraints and backoff​

object UploadWork {
    private const val UNIQUE_NAME = "photo_upload"

    fun buildRequest(
        uris: List<String>,
        userInitiated: Boolean
    ): OneTimeWorkRequest {
        val constraints = Constraints.Builder()
            .setRequiredNetworkType(NetworkType.UNMETERED) // or CONNECTED if you allow metered
            .build()

        return OneTimeWorkRequestBuilder<UploadWorker>()
            .setConstraints(constraints)
            .addTag(UNIQUE_NAME)
            .setBackoffCriteria(
                BackoffPolicy.EXPONENTIAL,
                30, TimeUnit.SECONDS
            )
            .setInputData(
                workDataOf(
                    UploadWorker.KEY_URIS to uris.toTypedArray(),
                    UploadWorker.KEY_USER_INITIATED to userInitiated
                )
            )
            // If user-initiated and you need it to start ASAP, consider expedited:
            // .setExpedited(OutOfQuotaPolicy.RUN_AS_NON_EXPEDITED_WORK_REQUEST)
            .build()
    }

    fun enqueue(
        context: Context,
        request: OneTimeWorkRequest
    ) {
        WorkManager.getInstance(context).enqueueUniqueWork(
            UNIQUE_NAME,
            ExistingWorkPolicy.APPEND_OR_REPLACE, // sequentialize batches
            request
        )
    }
}

Notes:

• Use APPEND or APPEND_OR_REPLACE to serialize uploads and avoid duplicates.
• Use expedited work only for truly immediate operations; quotas may downgrade it to non-expedited.

Step 4: Observe progress in a ViewModel and display in Compose​

ViewModel:

class UploadViewModel(
    private val appContext: Context
) : ViewModel() {

    private val workManager = WorkManager.getInstance(appContext)
    private val _workId = MutableStateFlow<UUID?>(null)

    val progress = _workId
        .flatMapLatest { id ->
            if (id == null) flowOf(0) else
                workManager.getWorkInfoByIdFlow(id).map {
                    it.progress.getInt(UploadWorker.KEY_PROGRESS, 0)
                }
        }
        .stateIn(viewModelScope, SharingStarted.Lazily, 0)

    fun startUpload(uris: List<String>, userInitiated: Boolean) {
        val request = UploadWork.buildRequest(uris, userInitiated)
        _workId.value = request.id
        UploadWork.enqueue(appContext, request)
    }

    fun cancel() {
        _workId.value?.let { workManager.cancelWorkById(it) }
    }
}

Compose UI:

@Composable
fun UploadScreen(vm: UploadViewModel) {
    val progress by vm.progress.collectAsState()

    Column(Modifier.padding(16.dp)) {
        Text("Upload progress: $progress%")
        LinearProgressIndicator(progress / 100f)
        Row {
            Button(onClick = {
                // Example: user picks 3 images
                vm.startUpload(uris = listOf("content://a", "content://b", "content://c"), userInitiated = true)
            }) { Text("Start upload") }
            Spacer(Modifier.width(8.dp))
            OutlinedButton(onClick = vm::cancel) { Text("Cancel") }
        }
    }
}

Why this avoids Android 17 FGS type errors​

• No background-started services. WorkManager coexists with JobScheduler and OS constraints, avoiding ForegroundServiceStartNotAllowedException.
• If and only if you enter foreground mode (setForeground), you:
  • Provide a ForegroundInfo with the correct type (DATA_SYNC).
  • Hold the matching permission (FOREGROUND_SERVICE_DATA_SYNC) on Android 14+.
• If the work doesn’t need a foreground session, you don’t request foreground service privileges at all.

Additional production considerations​

• Dependency injection: Inject your repository/uploader into Worker via Hilt’s HiltWorker or a custom WorkerFactory.
• Large files: Stream, chunk, and resume on retry. Avoid buffering entire files in memory.
• Network/backoff: Use exponential backoff + retry after 5xx/IO errors; treat 4xx as terminal.
• Constraints: Prefer CONNECTED for general cases; use UNMETERED if required by product.
• Foreground lifetime: Only call setForeground when actually doing long-running user-visible work. Drop back to background when possible to reduce user-facing churn and battery impact.
• Unique work: Tag and use enqueueUniqueWork to prevent duplicate runs from rapid user taps.
• App upgrades and process death: WorkManager persists requests; no custom boot receivers required.

Testing across Android 14–17​

• Deny notification permission on Android 13+ and ensure your UX still works. For foreground mode, guide the user to grant it if you want a richer notification; otherwise, prefer background execution without foreground mode for non-essential cases.
• Force background and sleep conditions:
  • adb shell cmd appops set your.app RUN_IN_BACKGROUND ignore
  • adb shell cmd deviceidle force-idle
• Verify foreground service types when used:
  • adb shell dumpsys activity services | grep SystemForegroundService
• Validate constraints by toggling Wi‑Fi/metered, battery saver, and charging state.

Troubleshooting​

• Crash: Service did not specify foregroundServiceType
  • In WorkManager, this happens if you call setForeground without ForegroundInfo specifying a type on Android 14+. Always pass ForegroundInfo(notificationId, notification, ServiceInfo.FOREGROUND_SERVICE_TYPE_XXX).
• SecurityException: Missing required permission for foreground service type
  • Add the matching uses-permission for the type (e.g., FOREGROUND_SERVICE_DATA_SYNC). Only add it if you truly run foreground workers.
• ForegroundServiceStartNotAllowedException
  • You’re starting a service from the background or without user initiation. Use WorkManager. Don’t call startForegroundService directly.
• Work never runs on some OEM devices
  • Ensure you aren’t doing blocking I/O on the main thread inside doWork.
  • Remove unrealistic constraints. Check WorkManager initialization logs. Consider avoiding expedited work unless necessary.
• Duplicated uploads
  • Use enqueueUniqueWork with APPEND/KEEP/REPLACE policy and meaningful tags.

Migration checklist​

• Identify all non-essential FGS use cases (uploads, syncs, backups).
• Replace with WorkManager:
  • OneTimeWorkRequest + Constraints + Backoff
  • Optional foreground mode with correct ForegroundInfo + permission
• Remove legacy service components from the manifest.
• Only keep FGS for system-approved continuous use cases.
• Add UI to observe WorkInfo and show user progress or state.
• Test on Android 14/15 and latest 17 preview builds with background restrictions.

Key takeaways​

• Most “Android 17 foreground service type” crashes are a symptom of using FGS for work that should be WorkManager.
• With WorkManager, you get reliability, OS compliance, and fewer sharp edges, while still retaining foreground mode for truly user-visible, long-running tasks.
• If you must use foreground mode, always set the correct type and permission via ForegroundInfo; otherwise, omit FGS entirely.
• Adopt constraints, retries, unique work, and progress reporting for a production-grade solution.

Next steps: Audit your app’s services, pick one deferrable feature (like uploads or sync), and migrate it using the patterns in this guide. Once you see the stability and policy-compliance improvements, repeat for the rest.

Android ANRs surface when the main (UI) thread is blocked long enough that the system stops trusting the process to respond. This post focuses on practical ways to diagnose UI thread blocking and main thread starvation, and how automated monitoring (including Appxiom) can detect UI hangs and reduce ANR rates in production.

What causes ANR in Android: UI thread blocking and main thread starvation​

ANR in Android typically occurs when:

• Input dispatch isn't handled within ~5s (Activity/Window focus and touch).
• Service starts/operations run too long (~10s).
• BroadcastReceiver execution exceeds its time budget (~200ms).

Common sources of UI thread blocking in Kotlin Android development:

• Disk I/O on the main thread (file, SharedPreferences, SQLite).
• Network calls accidentally executed on Dispatchers.Main or via runBlocking.
• Heavy JSON parsing, bitmap decoding, or crypto on the main thread.
• Over-synchronization or long critical sections that block the Looper.
• Infinite/long animations or tight loops starving the MessageQueue.
• Excessive work at startup (inflation, reflection, content providers).

Main thread starvation can happen even if no single call is “huge” but the Looper is constantly busy (e.g., tight re-posts to Dispatchers.Main.immediate, hot loops, too many tiny messages).

Kotlin Android development best practices to prevent ANRs​

• Move disk/network/CPU-heavy work off the main thread with coroutines:

class UserRepo(
    private val dao: UserDao,
    private val api: Api
) {
    suspend fun loadUser(userId: String): User = withContext(Dispatchers.IO) {
        val local = dao.getUser(userId)
        local ?: api.fetchUser(userId).also { dao.insert(it) }
    }
}

// UI layer
lifecycleScope.launch {
    try {
        val user = repo.loadUser("42") // switches to IO for work
        render(user)                   // back on Main
    } catch (t: Throwable) {
        showError(t)
    }
}

• Prefer Dispatchers.IO for blocking I/O, Dispatchers.Default for CPU work; keep Dispatchers.Main for minimal UI updates.
• Avoid runBlocking on the main thread; prefer suspend functions and structured concurrency.
• In Compose, use remember/derivedStateOf wisely; in Views, avoid deep nested layouts and heavy work in onDraw/onLayout.

Enable StrictMode in debug builds to catch disk/network on main:

if (BuildConfig.DEBUG) {
    StrictMode.setThreadPolicy(
        StrictMode.ThreadPolicy.Builder()
            .detectDiskReads()
            .detectDiskWrites()
            .detectNetwork()
            .penaltyLog()
            .build()
    )
}

Manual debugging: systrace/Perfetto, logs, and ANR traces​

1. Use Perfetto (successor to systrace) to visualize UI thread blocking:
   • Record a trace while reproducing the issue.
   • Inspect Main thread slices, Binder calls, CPU scheduling, and Choreographer frames.
   • Add lightweight markers:

Trace.beginSection("decodeBitmap")
// expensive decode off Main
Trace.endSection()

2. Inspect ANR traces:

   • Pull from bugreport or /data/anr/traces.txt (requires appropriate permissions).
   • Look for “main” thread stack at the time of ANR; identify blocking call (disk, network, lock).

3. Log Looper messages and frame jank locally:

   • JankStats (Jetpack) provides frame-dropped info tied to states:

val jankStats = JankStats.createAndTrack(window) { frameData ->
    if (frameData.isJank) {
        Log.w("Jank", "Jank frame: ${frameData.frameDurationUiNanos} ns, states=${frameData.states}")
    }
}

4. Correlate with app logs:
   • Time-stamp major operations.
   • Log key thread names and durations (e.g., DB queries, JSON parse) to see if they align with jank/ANR windows.

Automated UI hang detection in production​

If you only rely on system ANRs, you’ll miss many “near-ANR” stalls that hurt UX. A lightweight watchdog detects UI thread stalls earlier:

class UiBlockDetector(
    private val thresholdMs: Long = 700L
) {
    @Volatile private var lastBeat = SystemClock.uptimeMillis()
    private val handler = Handler(Looper.getMainLooper())

    private val ticker = object : Runnable {
        override fun run() {
            lastBeat = SystemClock.uptimeMillis()
            handler.post(this) // Re-post to run again on next loop spin
        }
    }

    fun start() {
        handler.post(ticker)
        Thread {
            while (!Thread.interrupted()) {
                val since = SystemClock.uptimeMillis() - lastBeat
                if (since > thresholdMs) {
                    // Main thread stalled; capture state for diagnostics
                    Log.e("UiBlock", "UI thread stall: ${since}ms")
                }
                Thread.sleep(thresholdMs / 2)
            }
        }.start()
    }
}

More robust implementations combine:

• Choreographer frame pacing to catch long frames.
• Periodic stack sampling of the main thread when a stall is suspected.
• Correlation with CPU/network/disk metrics to find bottlenecks.

How Appxiom helps reduce ANR rates​

In production, Appxiom detects UI thread blocking and main thread starvation by:

• Observing Choreographer and the main Looper to flag long frames and stalls before they escalate into an ANR in Android.
• Sampling main-thread stacks during stalls to pinpoint code paths (e.g., disk I/O, network, heavy parsing).
• Correlating stalls with screen, device, OS version, CPU load, network latency, and DB operations.
• Aggregating “near-ANR” and ANR events to reveal top offenders and trends over releases.

This automated approach complements manual systrace and logs, making it easier to prevent ANRs at scale.

Quick checklist to prevent ANRs​

• Never block Dispatchers.Main; use withContext(IO/Default) for I/O/CPU.
• Turn on StrictMode in debug and fix violations.
• Avoid runBlocking and long synchronized sections on UI paths.
• Use JankStats to monitor rendering jank; profile with Perfetto for deeper dives.
• Add Trace sections around expensive code.
• Deploy a UI stall watchdog in production and track main-thread stacks.
• Continuously monitor ANR rates and near-ANR stalls; regressions often appear early after releases.

By combining solid Kotlin coroutine practices, manual traces, and automated UI hang detection, teams can reduce ANR rates and deliver a responsive Android experience.