error-handling-result

Typed Error Handling (Kotlin / KMP)

Overview

In shared KMP code, prefer modeling expected failures as values over throwing across layers — it forces callers to handle them and crosses the iOS boundary cleanly. Three idiomatic tiers: kotlin.Result, sealed result types, and Arrow (Either/Raise).

When to use

• Designing how a repository or use case reports failure
• Network / parse / validation outcomes
• Deciding between exceptions, Result, sealed types, or Arrow
• Surfacing errors to Swift across the KMP boundary

Decision

Situation	Use
One-off wrap of a throwing call	runCatching { } → kotlin.Result
A domain with named, exhaustive error cases	sealed result type
Functional composition, short-circuit, no boxing	Arrow Either / Raise
Truly unexpected / programmer error	throw (don't model it)

Sealed result type (most KMP-friendly)

sealed interface LoadResult<out T> {
    data class Success<T>(val data: T) : LoadResult<T>
    data class Failure(val error: AppError) : LoadResult<Nothing>
}

enum class AppError { Network, NotFound, Unauthorized, Unknown }

when (val r = repo.load()) {
    is LoadResult.Success -> show(r.data)
    is LoadResult.Failure -> handle(r.error)   // compiler enforces exhaustiveness
}

kotlin.Result

val result: Result<User> = runCatching { api.fetchUser(id) }
result.map { it.toUiModel() }.getOrElse { e -> fallback(e) }

⚠️ runCatching also catches CancellationException — inside coroutines, rethrow it (see kotlin-coroutines).

Arrow Either + Raise

// build.gradle.kts: implementation("io.arrow-kt:arrow-core:<v>")
fun parsePort(s: String): Either<AppError, Int> = either {
    val n = s.toIntOrNull() ?: raise(AppError.Unknown)   // short-circuits
    ensure(n in 1..65535) { AppError.Unknown }
    n
}

val config: Either<AppError, Config> = either {
    val port = parsePort(raw).bind()                     // unwrap or short-circuit
    Config(port)
}