Fix App Hangs in Kotlin Multiplatform Apps (iOS)

App hangs in KMP apps (iOS and iPadOS)

An app hang happens when an iOS or iPadOS app stops responding to user input for 250 milliseconds or more. In a Kotlin Multiplatform (KMP) app, the iOS UI, whether SwiftUI, UIKit or Compose Multiplatform, runs on the main thread together with any shared Kotlin code called from it.

During a hang the interface freezes and taps, scrolls and gestures are ignored. Short hangs make the app feel sluggish; long ones lead users to force-quit the app.

App hangs are the iOS counterpart of ANRs on Android, and in KMP apps they often come from the same shared code, which means a fix in commonMain can improve both platforms.

Why does this happen?

App hangs in KMP iOS builds usually come from:

Blocking calls from Swift into shared code: Calling a Kotlin function synchronously from Swift on the main thread when that function does heavy work, file access or parsing.

runBlocking and main-dispatcher work: Shared code that uses runBlocking or runs expensive work on Dispatchers.Main blocks the iOS main thread.

Slow I/O: Database queries, file reads or synchronous network calls triggered from the UI.

Heavy Compose Multiplatform recomposition: Expensive calculations inside composables that run on every recomposition.

Deadlocks and lock contention: The main thread waiting on a lock or mutex held by a background coroutine or thread.

How to fix it using Appxiom

• Analyze stack trace: The issue report provides the stack trace of the main thread, pointing to the code that likely caused the hang.
• Trace activity trail: The activity trail, a chronologically ordered list of events before the issue, helps you retrace how the user was interacting with the app.
• No extra code needed: App hangs are tracked automatically once Ax.startIOS is called on iOS. See Crash & Error Reporting for KMP.