Managing Errors with Kotlin Union Types: A Practical Guide for Android Architecture

Handling errors effectively is a cornerstone of robust Android applications. Over time, the ecosystem has transitioned from traditional exception handling to nullable types, and more recently, generic wrappers like Result or custom sealed classes. While these approaches provide structure, they often introduce boilerplate and can obscure the API contract at the function boundary.

Kotlin's KEEP-0441 introduces a compelling alternative: Rich Errors, or Error Union Types. This proposal provides a native, type-safe mechanism to declare recoverable errors directly in function signatures. In this article, we will explore what error union types are, how to define them, and how they can streamline your application architecture.

Understanding Error Union Types

At its core, a union type allows a function to return a value that can be one of several distinct types. KEEP-0441 specifically proposes disjoint error unions, meaning a function can return a successful data type or one or more specific error types.

We represent this using the | operator:

This model provides several architectural advantages:

Explicit Contracts: The compiler enforces that callers handle the specific errors declared in the signature.
Flow Typing: Kotlin's smart-casting automatically resolves the remaining type possibilities once an error is checked.
Parallel Hierarchy: Error types implicitly extend a new synthetic Error supertype. They form a parallel hierarchy to Any, separating errors entirely from standard return values (null is not considered an error in this context).

Defining Error Types

Note: Rich Errors are currently a Kotlin Evolution and Enhancement Process (KEEP) proposal. To use them in future releases, you will likely need to opt-in via experimental compiler flags.

You define these types using the proposed error soft keyword. To ensure unions remain disjoint, error types cannot have superclasses, superinterfaces, or generic parameters.

To keep your domain layer clean, you can compose errors using a typealias:

Architectural Implementation in Android

Let’s look at how to integrate error union types into a modern, state-driven Android architecture.

The Repository Layer

Currently, repositories often return Flow<Result<T>> or a custom Resource<T> sealed class. With union types, the repository exposes a precise, expressive signature.

State Management in the ViewModel

When mapping domain models to UI state, exhaustive handling is critical. Because union types are disjoint, the Kotlin compiler will force you to evaluate every declared error state in a when expression, preventing unhandled edge cases from reaching production.

Ergonomics and Error Propagation

Kotlin’s existing nullability operators map elegantly to this new paradigm. The safe-call operator ?. will short-circuit on Error types exactly as it does on null, accumulating potential errors through the call chain.

For immediate control flow adjustments, the proposal introduces an ifError block. This is useful for early returns or logging side-effects before proceeding with the guaranteed success type.

Conclusion

KEEP-0441’s Rich Errors provide a rigorous, compiler-enforced mechanism for state management without the overhead of deeply nested generic wrappers. By clearly defining failure states at the API boundary and leaning into Kotlin's flow typing, we can engineer safer, more predictable architectures. Keep an eye on the upcoming Kotlin releases to begin migrating your domain boundaries to this pattern.

Page updated

Google Sites

Report abuse