Kotlin Multiplatform crash reporting on iOS and Android

On Android, a Kotlin Multiplatform app crashes like any other Android app, and any Android crash reporter sees the full Kotlin stack trace. On iOS it is harder. A Kotlin exception that escapes into Swift or Objective-C terminates the app, and an iOS crash reporter records the stack at the moment of termination. That stack points at the Swift call into Kotlin, not at the line that threw. To get useful reports you need three things. Mark functions Swift calls with @Throws, so expected errors become Swift errors. Install a Kotlin unhandled-exception hook that hands the real Kotlin stack trace to your crash reporter. Keep the dSYM files for your Kotlin framework. CrashKiOS does the hook work for Crashlytics and Bugsnag, and Sentry's and Bugsnag's KMP SDKs do it for their own back ends.

This guide explains the mechanics, compares the options fairly, and covers where Codeskop's KMP SDK fits. It is an early access beta. If you're building the Android side, Android ANRs: causes, detection and fixes and OkHttp interceptors for network monitoring apply directly. The Codeskop KMP & iOS docs cover the beta setup.

Why KMP crash reporting is hard on iOS#

Kotlin exceptions are unchecked; Swift errors are checked

Kotlin has no checked exceptions, while Swift only has checked errors. The Kotlin/Native interop docs spell out what happens at the boundary:

• A Kotlin function marked @Throws(SomeException::class) becomes an NSError*-producing method in Objective-C and a throws method in Swift. If it throws SomeException or a subclass, Swift receives an NSError.
• "Other Kotlin exceptions reaching Swift/Objective-C are considered unhandled and cause program termination."
• Non-suspend functions without @Throws don't propagate Kotlin exceptions at all. suspend functions without @Throws propagate only CancellationException.

So this shared-code function crashes an iOS app if the server returns bad JSON:

1// commonMain2class CartRepository(private val api: CartApi) {3    suspend fun loadCart(): Cart = api.fetchCart()   // throws SerializationException on malformed JSON4}

Annotating it lets Swift handle the failure:

1// commonMain2class CartRepository(private val api: CartApi) {3    @Throws(SerializationException::class, CancellationException::class)4    suspend fun loadCart(): Cart = api.fetchCart()5}

1do {2    let cart = try await repository.loadCart()3    show(cart)4} catch {5    showError(error)   // an NSError wrapping the Kotlin exception6}

@Throws is the right fix for expected errors. It does nothing for bugs you didn't anticipate, such as a NullPointerException deep in shared code. Those still terminate the app.

The crash report points at the wrong place

When an unhandled Kotlin exception terminates an iOS app, iOS crash reporters capture the threads at the moment of termination. Touchlab's CrashKiOS docs describe the result: "the crash report shows the point at which we call into Kotlin from Swift/Objc." Kotlin's own stack trace, the frames between the throw and the boundary, is gone unless something captured it before termination.

The unhandled exception hook

Kotlin/Native gives you a hook that runs before termination. These APIs live in kotlin.native and are marked @ExperimentalNativeApi:

• setUnhandledExceptionHook(hook) runs "whenever there is an uncaught exception reaching the boundaries of the Kotlin world", including an Objective-C-to-Kotlin call not marked @Throws. It returns the previous hook, so you can chain.
• terminateWithUnhandledException(throwable) terminates the program the same way the default behaviour does, without calling hooks. The runtime source recommends it for hooks that terminate the app.
• processUnhandledException(throwable) calls your hook if one is set; otherwise it terminates.

A minimal hook looks like this:

1// iosMain2@OptIn(ExperimentalNativeApi::class)3fun installCrashHook(report: (Throwable) -> Unit) {4    val previous = setUnhandledExceptionHook { throwable ->5        report(throwable)                       // capture the Kotlin stack trace now6        previous?.invoke(throwable)7        terminateWithUnhandledException(throwable)8    }9}

The hard part is report. It has to persist the Kotlin stack trace in a form your crash reporter can show and symbolicate, before the process dies. That is what the libraries below do.

Symbolication and dSYMs

Kotlin frames in an iOS crash report are memory addresses until they're symbolicated. Per the Kotlin/Native debugging docs, the compiler "generates .dSYM files for release (optimized) binaries on Apple platforms by default", and Xcode picks them up from the standard locations. Your crash tool needs the dSYM that matches each build. With a dynamic framework, the Kotlin framework's .dSYM may need uploading separately; CrashKiOS documents the "Missing UUID" error you get otherwise.

On Android, the equivalent is the R8 mapping.txt for each release.

The options in the ecosystem#

CrashKiOS and Kermit (Crashlytics or Bugsnag)

CrashKiOS is a "thin library that provides symbolicated crash reports for Kotlin code on iOS". It supports crashes, handled exceptions, breadcrumbs and custom keys, sending to Firebase Crashlytics or Bugsnag. For Crashlytics you add co.touchlab.crashkios:crashlytics, call enableCrashlytics(), and in iOS startup code call setCrashlyticsUnhandledExceptionHook(). There are two documented gotchas. You need to disable the Kotlin/Native compiler cache for simulator targets (kotlin.native.cacheKind.iosSimulatorArm64=none). Dynamic frameworks need the co.touchlab.crashkios.crashlyticslink Gradle plugin. Kermit, Touchlab's logging library, adds CrashlyticsLogWriter and BugsnagLogWriter so log lines become breadcrumbs.

Good fit if you already use Crashlytics (it's free; see our Crashlytics comparison) or Bugsnag and want proper Kotlin stack traces on iOS. Note that Google ships no official KMP SDK; the community GitLive Firebase Kotlin SDK wraps the official SDKs for other Firebase APIs.

Sentry's KMP SDK

Sentry's SDK wraps its Android and Cocoa SDKs for Android, JVM, iOS, macOS, watchOS and tvOS. JS, Wasm, Linux and Windows targets compile but do nothing at runtime. You initialise with Sentry.init { options -> options.dsn = "..." } from shared code, and on iOS it installs an unhandled-exception hook automatically. Each KMP release is pinned to a specific sentry-cocoa version, so check the compatibility table when upgrading. dSYM upload follows Sentry's iOS docs. Sentry is also the broadest option, with tracing, profiling and session replay on its native SDKs (see Sentry vs Codeskop).

Bugsnag's KMP SDK

Bugsnag reached 1.0.0 for KMP in September 2025, covering Android, iOS and web. You add com.bugsnag:bugsnag-kmp and the bugsnag-cocoa package for iOS, then call Bugsnag.start(configuration).

Where Codeskop fits (early access beta)#

Codeskop's Kotlin Multiplatform and iOS support is an early access beta. The core is the same Kotlin SDK that powers our generally available Android and Flutter releases, but the setup and API may change before general availability. Here is what the beta covers, per the KMP docs:

• Shared code (commonMain): identify, reset, recordException, setEnabled and flush.
• Android target: everything in the Android SDK: crashes, ANRs and OkHttp network capture.
• iOS (14 or later): uncaught exceptions and crash signals are captured automatically once the SDK starts, with the same on-device queue as Android, so reports survive being offline.
• Not in the beta yet: there's no Ktor client plugin, so network capture from shared code isn't automatic, and URLSession requests on iOS aren't captured automatically. Beta teams get a reference URLProtocol subclass (under 100 lines) that forwards failures to Codeskop.shared.captureApiError(call:).

Setup in the shared module:

1kotlin {2    sourceSets {3        commonMain.dependencies {4            implementation("com.codeskop.sdk:tracker-core:0.3.0")5        }6        androidMain.dependencies {7            implementation("com.codeskop.sdk:tracker-android:0.3.0")8            implementation("com.codeskop.sdk:tracker-okhttp:0.3.0") // optional network capture9        }10    }11}

Initialise on Android, then report from shared code:

1// androidMain: initialize once, e.g. in Application.onCreate2CodeskopAndroid.init(3    context,4    CodeskopConfig(apiKey = BuildConfig.CODESKOP_KEY),5)

1// commonMain: identify and report from shared code2Codeskop.identify(userId = user.id)3 4try {5    syncCart()6} catch (e: Exception) {7    Codeskop.recordException(e)8}

On iOS, the SDK is a Swift package (https://github.com/Codeskop-io/mobile-sdk.git), served from a private repository during the beta. Start it once at launch:

1import CodeskopSDK2 3// Swift needs every CodeskopConfig parameter spelled out4let config = CodeskopConfig(5    apiKey: "cs_live_pk_xxx",6    endpoint: "https://api.codeskop.com",7    environment: "production",8    sampleRates: [:],9    captureNetwork: true,10    captureHeaders: true,11    captureBodies: false,12    redactHeaders: ["authorization", "cookie", "set-cookie"],13    redactQueryKeys: ["token", "apikey", "password", "secret"],14    maxQueueMb: 10,15    heartbeatEnabled: true,16    flushBatchSize: 5017)18CodeskopIos.shared.start(config: config)19 20// At login21Codeskop.shared.identify(userId: user.id, traits: [:])

Every parameter is spelled out because Kotlin default values don't carry over to the generated Swift initialiser.

Who it suits today: teams that want one tool across a KMP app's Android and iOS sides, plus web and React, with crash and network failures in one place and public pricing (Free: 10,000 events/month; paid from $49/month as of October 2026, see pricing). Paid plans are billed in USD by card, and teams in Kenya can pay with M-Pesa GlobalPay's virtual Visa card. If you need production-grade iOS crash reporting today, with dSYM-symbolicated Kotlin frames and years of hardening, the established options above are the safer choice, and you can revisit Codeskop at general availability.

A checklist for KMP crash reporting#

1. Add @Throws to every shared function Swift calls that can fail for expected reasons (network, parsing, validation), including CancellationException for suspend functions.
2. Install an unhandled-exception hook on iOS, yourself or through your SDK, and chain to the previous hook.
3. Archive the Kotlin framework's dSYM for every iOS build, and mapping.txt for every Android release.
4. Test a deliberate crash from shared code on a real iOS device in a release build, and check that the report shows the Kotlin line.
5. Report handled exceptions from commonMain, so failures you recover from still show up.