# Exception Handling in Kotlin: runCatching and Result<T>

**Repository:** https://github.com/Yang92047111/exception-handling-kotlin

## Introduction

Exception handling has been a cornerstone of robust software development since the early days of programming. The traditional `try-catch` approach has served us well in Java and many other languages - it's simple, intuitive, and "just works". However, as software development has evolved, so have our approaches to handling errors and exceptional conditions.

Kotlin, with its focus on developer experience, versatility, and cleaner code, has introduced innovative approaches to exception handling that go beyond the traditional paradigm. As Kotlin continues to expand its reach into Multiplatform development, Server-side programming, and even emerging fields like AI (through frameworks like Koog for building Agentic AIs), it's crucial to understand these modern exception handling patterns.

This tutorial explores how `runCatching` and `Result<T>` can revolutionize the way we think about and handle exceptions in Kotlin.

## Table of Contents

1. [Traditional Exception Handling: The Try-Catch Era](#Traditional-Exception-Handling)
2. [Problems with Traditional Exception Handling](#Problems-with-Traditional-Exception-Handling)
3. [Enter Kotlin's runCatching](#Enter-Kotlins-Runcatching)
4. [Understanding Result<T>](#Understanding-Resultt)
5. [Practical Examples](#Practical-Examples)
6. [Advanced Patterns](#Advanced-Patterns)
7. [Best Practices](#Best-Practices)
8. [Performance Considerations](#Performance-Considerations)
9. [Migration Strategies](#Migration-Strategies)
10. [Conclusion](#Conclusion)

## Traditional Exception Handling

### The Classic Try-Catch Approach

For decades, developers have relied on the try-catch mechanism:

fun traditionalApproach(): String? {
    return try {
        // Some operation that might fail
        riskyOperation()
    } catch (e: Exception) {
        // Handle the exception
        println("Error occurred: ${e.message}")
        null
    }
}

fun riskyOperation(): String {
    // Simulate a risky operation
    if (Math.random() > 0.5) {
        throw RuntimeException("Something went wrong!")
    }
    return "Success!"
}

### Why Try-Catch Has Served Us Well

- **Simplicity**: Easy to understand and implement
- **Familiarity**: Widely adopted across programming languages
- **Control Flow**: Clear separation between normal and exceptional paths
- **Stack Unwinding**: Automatic cleanup of resources

## Problems with Traditional Exception Handling

### 1. Hidden Control Flow

Exceptions create hidden control flow that's not evident from the method signature:

fun processUser(userId: String): User {
    // This method signature doesn't tell us it can throw exceptions
    val user = userRepository.findById(userId) // Might throw SQLException
    val profile = profileService.getProfile(user.id) // Might throw NetworkException
    return user.copy(profile = profile)
}

### 2. Performance Overhead

Exception creation and stack trace generation can be expensive:

// Creating exceptions repeatedly can impact performance
fun findUserQuietly(id: String): User? {
    return try {
        userService.findUser(id) // Throws UserNotFoundException
    } catch (e: UserNotFoundException) {
        null // Converting exception to null - expensive!
    }
}

### 3. Inconsistent Error Handling

Different developers handle exceptions differently:

// Developer A
fun serviceA(): String? {
    return try {
        doSomething()
    } catch (e: Exception) {
        null
    }
}

// Developer B
fun serviceB(): String {
    return try {
        doSomething()
    } catch (e: Exception) {
        throw ServiceException("Service B failed", e)
    }
}

### 4. Forgotten Exception Handling

Easy to forget handling exceptions, leading to crashes:

fun dangerousCode() {
    // Forgot to handle potential SQLException
    database.executeQuery("SELECT * FROM users")
}

## Enter Kotlin's runCatching

### What is runCatching?

`runCatching` is Kotlin's functional approach to exception handling that wraps operations in a `Result<T>` type:

inline fun <T> runCatching(block: () -> T): Result<T>

### Basic Usage

fun modernApproach(): Result<String> {
    return runCatching {
        riskyOperation()
    }
}

// Usage
val result = modernApproach()
when {
    result.isSuccess -> println("Success: ${result.getOrNull()}")
    result.isFailure -> println("Failed: ${result.exceptionOrNull()?.message}")
}

### Benefits of runCatching

1. **Explicit Error Handling**: The return type `Result<T>` makes it clear that the operation can fail
2. **Functional Style**: Encourages functional programming patterns
3. **Composability**: Easy to chain operations
4. **Performance**: No stack trace generation for expected failures

## Understanding Result<T>

### The Result<T> Type

`Result<T>` is a discriminated union that represents either a successful value or a failure:

sealed class Result<out T> {
    // Success case
    data class Success<out T>(val value: T) : Result<T>()
    
    // Failure case  
    data class Failure(val exception: Throwable) : Result<Nothing>()
}

### Key Methods of Result<T>

#### Checking Success/Failure

val result = runCatching { "Hello World" }

// Check if successful
if (result.isSuccess) {
    println("Operation succeeded")
}

// Check if failed
if (result.isFailure) {
    println("Operation failed")
}

#### Getting Values

val result = runCatching { 42 }

// Get value or null
val value: Int? = result.getOrNull()

// Get value or default
val valueOrDefault: Int = result.getOrDefault(0)

// Get value or else
val valueOrElse: Int = result.getOrElse { -1 }

// Get value or throw
val value: Int = result.getOrThrow()

#### Getting Exceptions

val result = runCatching { throw RuntimeException("Oops!") }

// Get exception or null
val exception: Throwable? = result.exceptionOrNull()

## Practical Examples

### Example 1: File Operations

#### Traditional Approach

fun readFileTraditional(filename: String): String? {
    return try {
        File(filename).readText()
    } catch (e: IOException) {
        println("Failed to read file: ${e.message}")
        null
    } catch (e: SecurityException) {
        println("Permission denied: ${e.message}")
        null
    }
}

#### Modern Approach with runCatching

fun readFileModern(filename: String): Result<String> {
    return runCatching {
        File(filename).readText()
    }
}

// Usage
fun processFile(filename: String) {
    readFileModern(filename)
        .onSuccess { content ->
            println("File content: $content")
        }
        .onFailure { exception ->
            when (exception) {
                is IOException -> println("IO Error: ${exception.message}")
                is SecurityException -> println("Permission denied: ${exception.message}")
                else -> println("Unexpected error: ${exception.message}")
            }
        }
}

### Example 2: Network Operations

class ApiService {
    fun fetchUser(id: String): Result<User> {
        return runCatching {
            // Simulate network call
            if (id.isEmpty()) throw IllegalArgumentException("User ID cannot be empty")
            if (id == "404") throw UserNotFoundException("User not found")
            
            User(id, "John Doe", "[e-mail]")
        }
    }
    
    fun fetchUserProfile(userId: String): Result<UserProfile> {
        return runCatching {
            // Simulate another network call
            UserProfile(userId, "Software Engineer", "New York")
        }
    }
}

data class User(val id: String, val name: String, val email: String)
data class UserProfile(val userId: String, val job: String, val location: String)
class UserNotFoundException(message: String) : Exception(message)

### Example 3: Chaining Operations

fun getUserWithProfile(userId: String): Result<Pair<User, UserProfile>> {
    val apiService = ApiService()
    
    return apiService.fetchUser(userId)
        .mapCatching { user ->
            // If user fetch succeeds, fetch profile
            val profileResult = apiService.fetchUserProfile(user.id)
            user to profileResult.getOrThrow()
        }
}

// Usage
fun displayUserInfo(userId: String) {
    getUserWithProfile(userId)
        .onSuccess { (user, profile) ->
            println("User: ${user.name} - ${profile.job} in ${profile.location}")
        }
        .onFailure { exception ->
            println("Failed to get user info: ${exception.message}")
        }
}

## Advanced Patterns

### 1. Result Transformation

#### map and mapCatching

fun processNumber(input: String): Result<String> {
    return runCatching { input.toInt() }
        .map { it * 2 }  // Transform success value
        .map { "Result: $it" }
}

fun processNumberSafely(input: String): Result<String> {
    return runCatching { input.toInt() }
        .mapCatching { number ->
            if (number < 0) throw IllegalArgumentException("Negative numbers not allowed")
            "Processed: ${number * 2}"
        }
}

#### flatMap Pattern

fun parseAndValidateAge(input: String): Result<Int> {
    return runCatching { input.toInt() }
        .flatMap { age ->
            if (age in 0..150) Result.success(age)
            else Result.failure(IllegalArgumentException("Invalid age: $age"))
        }
}

### 2. Combining Multiple Results

fun combineResults(
    result1: Result<String>,
    result2: Result<Int>
): Result<String> {
    return result1.flatMap { str ->
        result2.map { num ->
            "$str: $num"
        }
    }
}

// Using a more functional approach
fun combineResultsFunctional(
    result1: Result<String>,
    result2: Result<Int>
): Result<String> {
    return runCatching {
        val str = result1.getOrThrow()
        val num = result2.getOrThrow()
        "$str: $num"
    }
}

### 3. Error Recovery

fun fetchDataWithFallback(primaryUrl: String, fallbackUrl: String): Result<String> {
    return runCatching { fetchFromUrl(primaryUrl) }
        .recoverCatching { exception ->
            println("Primary failed (${exception.message}), trying fallback")
            fetchFromUrl(fallbackUrl)
        }
}

fun fetchFromUrl(url: String): String {
    // Simulate network fetch
    if (url.contains("primary")) throw IOException("Primary server down")
    return "Data from $url"
}

### 4. Validation Pipelines

data class UserInput(
    val email: String,
    val age: String,
    val name: String
)

data class ValidatedUser(
    val email: String,
    val age: Int,
    val name: String
)

fun validateUser(input: UserInput): Result<ValidatedUser> {
    return runCatching {
        val validatedEmail = validateEmail(input.email).getOrThrow()
        val validatedAge = validateAge(input.age).getOrThrow()
        val validatedName = validateName(input.name).getOrThrow()
        
        ValidatedUser(validatedEmail, validatedAge, validatedName)
    }
}

fun validateEmail(email: String): Result<String> {
    return runCatching {
        if (!email.contains("@")) throw IllegalArgumentException("Invalid email format")
        email
    }
}

fun validateAge(age: String): Result<Int> {
    return runCatching { age.toInt() }
        .flatMap { ageInt ->
            if (ageInt in 0..150) Result.success(ageInt)
            else Result.failure(IllegalArgumentException("Age must be between 0 and 150"))
        }
}

fun validateName(name: String): Result<String> {
    return runCatching {
        if (name.isBlank()) throw IllegalArgumentException("Name cannot be blank")
        name.trim()
    }
}

## Best Practices

### 1. When to Use runCatching

✅ **Use runCatching when:**
- Operations can fail predictably
- You want to make error handling explicit
- You're building functional pipelines
- Performance is critical and exceptions are expected

❌ **Don't use runCatching when:**
- Dealing with truly exceptional conditions
- You need to preserve stack traces for debugging
- Working with legacy code that expects exceptions

### 2. Naming Conventions

// Good: Clear that operation can fail
fun tryParseInt(input: String): Result<Int>
fun fetchUserSafely(id: String): Result<User>

// Better: Use Result<T> in return type to be explicit
fun parseInteger(input: String): Result<Int>
fun getUser(id: String): Result<User>

### 3. Error Messages

// Good: Descriptive error messages
fun validatePositiveNumber(input: String): Result<Int> {
    return runCatching { input.toInt() }
        .flatMap { number ->
            if (number > 0) Result.success(number)
            else Result.failure(IllegalArgumentException("Expected positive number, got: $number"))
        }
}

### 4. Resource Management

fun processFileWithResources(filename: String): Result<String> {
    return runCatching {
        File(filename).useLines { lines ->
            lines.map { it.uppercase() }.joinToString("\n")
        }
    }
}

## Performance Considerations

### Benchmarking: Exception vs Result

// Exception-based approach (slower for expected failures)
fun parseIntWithException(input: String): Int? {
    return try {
        input.toInt()
    } catch (e: NumberFormatException) {
        null
    }
}

// Result-based approach (faster for expected failures)
fun parseIntWithResult(input: String): Result<Int> {
    return runCatching { input.toInt() }
}

// Performance test scenario
fun performanceTest() {
    val invalidInputs = List(10000) { "invalid$it" }
    
    // Exception approach will be slower due to stack trace creation
    val startException = System.currentTimeMillis()
    invalidInputs.forEach { parseIntWithException(it) }
    val endException = System.currentTimeMillis()
    
    // Result approach will be faster
    val startResult = System.currentTimeMillis()
    invalidInputs.forEach { parseIntWithResult(it) }
    val endResult = System.currentTimeMillis()
    
    println("Exception approach: ${endException - startException}ms")
    println("Result approach: ${endResult - startResult}ms")
}

### Memory Considerations

// Result<T> has minimal memory overhead
// Exception objects can be heavy due to stack traces

fun lightweightErrorHandling(): Result<String> {
    return runCatching {
        // No stack trace generation unless exception actually occurs
        "success"
    }
}

## Migration Strategies

### 1. Gradual Migration

// Step 1: Wrap existing exception-throwing code
fun legacyFunction(): String {
    throw RuntimeException("Legacy error")
}

fun wrappedLegacyFunction(): Result<String> {
    return runCatching { legacyFunction() }
}

// Step 2: Refactor consumers
fun consumer() {
    wrappedLegacyFunction()
        .onSuccess { value -> println("Success: $value") }
        .onFailure { error -> println("Error: ${error.message}") }
}

### 2. API Boundary Strategy

// Keep exceptions at API boundaries, use Result internally
class UserService {
    // Internal use - Result based
    private fun fetchUserInternal(id: String): Result<User> {
        return runCatching {
            // Implementation
            User(id, "John", "[e-mail]")
        }
    }
    
    // Public API - exception based for compatibility
    @Throws(UserNotFoundException::class)
    fun getUser(id: String): User {
        return fetchUserInternal(id).getOrElse {
            throw UserNotFoundException("User $id not found")
        }
    }
    
    // New public API - Result based
    fun getUserSafely(id: String): Result<User> {
        return fetchUserInternal(id)
    }
}

### 3. Testing Strategy

class UserServiceTest {
    
    @Test
    fun `should return success when user exists`() {
        val service = UserService()
        val result = service.getUserSafely("123")
        
        assertTrue(result.isSuccess)
        assertEquals("John", result.getOrNull()?.name)
    }
    
    @Test
    fun `should return failure when user not found`() {
        val service = UserService()
        val result = service.getUserSafely("999")
        
        assertTrue(result.isFailure)
        assertTrue(result.exceptionOrNull() is UserNotFoundException)
    }
}

## Real-World Use Cases

### 1. Configuration Loading

class ConfigurationLoader {
    fun loadConfig(path: String): Result<AppConfig> {
        return runCatching { File(path).readText() }
            .mapCatching { content -> Json.decodeFromString<AppConfig>(content) }
            .mapCatching { config -> validateConfig(config) }
    }
    
    private fun validateConfig(config: AppConfig): AppConfig {
        if (config.port !in 1..65535) {
            throw IllegalArgumentException("Invalid port: ${config.port}")
        }
        return config
    }
}

@Serializable
data class AppConfig(
    val host: String,
    val port: Int,
    val database: DatabaseConfig
)

@Serializable
data class DatabaseConfig(
    val url: String,
    val username: String
)

### 2. Data Processing Pipeline

class DataProcessor {
    fun processUserData(rawData: String): Result<ProcessedUser> {
        return parseUserData(rawData)
            .flatMap { userData -> validateUser(userData) }
            .flatMap { validUser -> enrichUserData(validUser) }
            .map { enrichedUser -> ProcessedUser(enrichedUser) }
    }
    
    private fun parseUserData(raw: String): Result<RawUser> {
        return runCatching {
            Json.decodeFromString<RawUser>(raw)
        }
    }
    
    private fun validateUser(user: RawUser): Result<ValidUser> {
        return runCatching {
            if (user.email.isBlank()) throw IllegalArgumentException("Email required")
            if (user.age < 0) throw IllegalArgumentException("Invalid age")
            ValidUser(user.email, user.age, user.name)
        }
    }
    
    private fun enrichUserData(user: ValidUser): Result<EnrichedUser> {
        return runCatching {
            // Simulate external service call
            val additionalInfo = fetchAdditionalInfo(user.email).getOrThrow()
            EnrichedUser(user.email, user.age, user.name, additionalInfo)
        }
    }
    
    private fun fetchAdditionalInfo(email: String): Result<String> {
        return runCatching {
            // Simulate API call
            "Additional info for $email"
        }
    }
}

@Serializable
data class RawUser(val email: String, val age: Int, val name: String)
data class ValidUser(val email: String, val age: Int, val name: String)
data class EnrichedUser(val email: String, val age: Int, val name: String, val additionalInfo: String)
data class ProcessedUser(val enrichedUser: EnrichedUser)

### 3. Network Client with Retry Logic

class HttpClient {
    suspend fun fetchWithRetry(url: String, maxRetries: Int = 3): Result<String> {
        var lastError: Throwable? = null
        
        repeat(maxRetries) { attempt ->
            val result = runCatching { performRequest(url) }
            
            result.onSuccess { return it }
            result.onFailure { error ->
                lastError = error
                if (attempt < maxRetries - 1) {
                    delay(1000 * (attempt + 1)) // Exponential backoff
                }
            }
        }
        
        return Result.failure(lastError ?: RuntimeException("Unknown error"))
    }
    
    private suspend fun performRequest(url: String): Result<String> {
        return runCatching {
            // Simulate HTTP request
            if (Math.random() > 0.7) throw IOException("Network error")
            "Response from $url"
        }
    }
}

## Integration with Coroutines

### Async Exception Handling

class AsyncService {
    suspend fun fetchMultipleUsers(ids: List<String>): Result<List<User>> {
        return runCatching {
            ids.map { id ->
                async { fetchUser(id).getOrThrow() }
            }.awaitAll()
        }
    }
    
    suspend fun fetchUsersConcurrently(ids: List<String>): List<Result<User>> {
        return ids.map { id ->
            async { runCatching { fetchUser(id).getOrThrow() } }
        }.awaitAll()
    }
    
    private suspend fun fetchUser(id: String): Result<User> {
        return runCatching {
            delay(100) // Simulate network delay
            User(id, "User $id", "$[e-mail]")
        }
    }
}

## Comparison with Other Languages

### Rust's Result Type

Kotlin's `Result<T>` is inspired by Rust's `Result<T, E>`:

// Kotlin
fun divide(a: Int, b: Int): Result<Int> {
    return if (b == 0) {
        Result.failure(ArithmeticException("Division by zero"))
    } else {
        Result.success(a / b)
    }
}

// Similar to Rust:
// fn divide(a: i32, b: i32) -> Result<i32, String> {
//     if b == 0 {
//         Err("Division by zero".to_string())
//     } else {
//         Ok(a / b)
//     }
// }

### Functional Languages

Similar patterns exist in functional languages:

// Kotlin Result is similar to:
// - Haskell's Either
// - Scala's Either or Try
// - F#'s Result

## Common Pitfalls and How to Avoid Them

### 1. Ignoring Failures

// ❌ Bad: Ignoring potential failures
fun badExample(input: String) {
    val result = runCatching { input.toInt() }
    val value = result.getOrNull()!! // Can throw NPE!
}

// ✅ Good: Proper handling
fun goodExample(input: String): String {
    return runCatching { input.toInt() }
        .fold(
            onSuccess = { "Parsed: $it" },
            onFailure = { "Failed to parse: ${it.message}" }
        )
}

### 2. Overusing runCatching

// ❌ Bad: Using runCatching for simple validation
fun validatePositive(number: Int): Result<Int> {
    return runCatching {
        if (number > 0) number
        else throw IllegalArgumentException("Must be positive")
    }
}

// ✅ Good: Direct Result creation for validation
fun validatePositive(number: Int): Result<Int> {
    return if (number > 0) {
        Result.success(number)
    } else {
        Result.failure(IllegalArgumentException("Must be positive"))
    }
}

### 3. Losing Error Context

// ❌ Bad: Losing original error information
fun processData(input: String): Result<String> {
    return runCatching { input.toInt() }
        .map { it.toString() }
        .recover { "default" } // Lost information about why it failed
}

// ✅ Good: Preserving error context
fun processData(input: String): Result<String> {
    return runCatching { input.toInt() }
        .map { it.toString() }
        .recoverCatching { originalError ->
            throw ProcessingException("Failed to process input: $input", originalError)
        }
}

class ProcessingException(message: String, cause: Throwable) : Exception(message, cause)

## Tools and Libraries

### 1. Arrow Library

For more advanced functional programming patterns:

// Arrow provides additional functional constructs
import arrow.core.Either
import arrow.core.getOrElse

fun arrowExample(input: String): Either<String, Int> {
    return Either.catch { input.toInt() }
        .mapLeft { "Failed to parse: ${it.message}" }
}

### 2. Testing Utilities

// Custom matchers for testing Result types
fun <T> Result<T>.shouldBeSuccess(): T {
    assertTrue(isSuccess, "Expected success but was failure: ${exceptionOrNull()}")
    return getOrThrow()
}

fun <T> Result<T>.shouldBeFailure(): Throwable {
    assertTrue(isFailure, "Expected failure but was success: ${getOrNull()}")
    return exceptionOrNull()!!
}

// Usage in tests
@Test
fun `should parse valid integer`() {
    val result = parseInteger("42")
    val value = result.shouldBeSuccess()
    assertEquals(42, value)
}

## Future Directions

### Sealed Classes for Specific Errors

sealed class ParseError {
    object EmptyInput : ParseError()
    data class InvalidFormat(val input: String) : ParseError()
    data class OutOfRange(val value: Int, val range: IntRange) : ParseError()
}

fun parseIntegerAdvanced(input: String): Result<Int> {
    return when {
        input.isEmpty() -> Result.failure(IllegalArgumentException("Empty input"))
        !input.all { it.isDigit() || it == '-' } -> 
            Result.failure(IllegalArgumentException("Invalid format: $input"))
        else -> runCatching { input.toInt() }
            .flatMap { value ->
                if (value in Int.MIN_VALUE..Int.MAX_VALUE) Result.success(value)
                else Result.failure(IllegalArgumentException("Out of range: $value"))
            }
    }
}

### Integration with Type-Safe Builders

class ValidationBuilder<T> {
    private val validators = mutableListOf<(T) -> Result<T>>()
    
    fun validate(validator: (T) -> Result<T>) {
        validators.add(validator)
    }
    
    fun build(): (T) -> Result<T> = { input ->
        validators.fold(Result.success(input)) { acc, validator ->
            acc.flatMap(validator)
        }
    }
}

fun createUserValidator(): (UserInput) -> Result<ValidatedUser> {
    return ValidationBuilder<UserInput>().apply {
        validate { input ->
            if (input.email.contains("@")) Result.success(input)
            else Result.failure(IllegalArgumentException("Invalid email"))
        }
        validate { input ->
            runCatching { input.age.toInt() }
                .flatMap { age ->
                    if (age in 0..150) Result.success(input)
                    else Result.failure(IllegalArgumentException("Invalid age"))
                }
        }
    }.build().let { validator ->
        { input ->
            validator(input).map { validInput ->
                ValidatedUser(validInput.email, validInput.age.toInt(), validInput.name)
            }
        }
    }
}

## Conclusion

The evolution from traditional try-catch exception handling to Kotlin's `runCatching` and `Result<T>` represents a significant shift in how we think about error handling. This modern approach offers several key advantages:

### Key Benefits Recap

1. **Explicit Error Handling**: The type system forces you to consider failure cases
2. **Functional Composition**: Easy to chain and transform operations
3. **Performance**: Better performance for expected failures
4. **Clarity**: Code intentions are clearer and more maintainable
5. **Testing**: Easier to test both success and failure paths

### When to Adopt

Consider adopting `runCatching` and `Result<T>` when:

- Building new Kotlin projects
- Working with functional programming patterns
- Dealing with operations that commonly fail
- Performance is critical
- You want more explicit error handling

### The Bigger Picture

As Kotlin continues to expand into new domains—from Multiplatform development to server-side programming and emerging technologies like AI frameworks—having robust, explicit error handling becomes increasingly important. The `runCatching` and `Result<T>` pattern provides a solid foundation for building reliable, maintainable applications.

The shift from exceptions to explicit error types represents a broader trend in programming language design toward making error conditions more visible and manageable. By embracing these patterns, you're not just writing better Kotlin code—you're adopting a mindset that will serve you well across the evolving landscape of software development.

### Next Steps

1. **Experiment**: Try converting some of your existing try-catch blocks to use `runCatching`
2. **Measure**: Compare performance in your specific use cases
3. **Iterate**: Gradually adopt the patterns that work best for your team and projects
4. **Share**: Help your team understand the benefits and trade-offs

Remember, the goal isn't to eliminate all exceptions, but to use the right tool for the right situation. Traditional exceptions still have their place for truly exceptional conditions, while `runCatching` and `Result<T>` excel for predictable failure scenarios.