Sealed classes and interfaces

What it is and why it exists

A sealed type represents a controlled inheritance hierarchy. The compiler knows which named types may inherit from it directly, so it can decide whether a when covers every possible case. After you add a case that needs distinct handling, old exhaustive decisions stop compiling and expose omissions before release.

This constraint fits domains with a finite set of forms whose payloads differ. A load operation, for example, can be in progress, carry retrieved data, or carry a failure reason. An enum can list fixed instances but can’t give each entry a different property shape, while a regular interface admits implementations the compiler doesn’t know about.

Sealed types commonly represent result types, UI states, protocol messages, commands, and abstract syntax trees. They aren’t error-handling frameworks and don’t validate state transitions automatically. They provide the boundary of a type set; constructors and handling functions still express the business rules.

A sealed class is abstract. It can have constructors, hold instance state, and provide protected members. A class can inherit from only one class, so choosing a sealed class occupies that inheritance position. Use one when every variant needs shared state or implementation.

A sealed interface has no constructor state, but a class can implement several interfaces. It usually fits when one variant belongs to two controlled classifications or when you only need a behavioral contract. Both forms support exhaustive when; state ownership and composition are the main differences.

A sealed hierarchy is an intentionally closed extension point. If third-party modules, local plugins, or application features need to add implementations freely, use a regular interface and handle unknown implementations explicitly. Modeling an open ecosystem as sealed merely turns valid extensions into compilation errors.

How it works

The direct-subtype boundary

A direct subtype of a sealed class or interface must be in the same package and module. It may be top-level or nested inside any number of named classes, interfaces, or objects, but it needs a qualified name. Local classes and anonymous objects can’t inherit directly from a sealed type.

“Direct” matters. If NetworkFailure implements Failure directly, package and module restrictions apply to it. If NetworkFailure is itself open, code in other packages can still extend it. The sealed parent controls the first boundary; every direct subtype’s own modifiers determine later extension.

Regular Kotlin classes are final by default, and data classes and objects can’t be extended. To organize variants into layers, make a direct subtype sealed as well. The compiler follows those sealed nodes until it reaches the non-sealed leaves that must be covered.

In the hierarchy below, the direct subtypes of Failure are the sealed IoFailure and the final Rejected. A decision over Failure can cover the whole I/O subtree with one is IoFailure branch, or it can distinguish Offline from Timeout.

How when proves exhaustiveness

An exhaustive when guarantees that every possible value of its subject matches a branch. A when used as an expression to return a value must be exhaustive. With a sealed subject, covering the relevant subtypes lets you omit else.

The compiler reasons about the set of “direct non-sealed subtypes.” When an intermediate node remains sealed, it continues down the hierarchy. Once a direct node is non-sealed, one type check for that node covers all of its possible descendants. Exhaustiveness therefore proves coverage of type boundaries, not that every concrete runtime class appears separately in source.

An is check in a branch also enables a smart cast . Once the compiler proves that the value has a subtype, the branch can access that subtype’s properties directly. There is no runtime reflection registry here; adding a subtype produces feedback when affected source is recompiled.

Writing else over a closed domain is legal but weakens that feedback. If you later add Expired, an existing else -> "unknown" still compiles, and the new business state silently takes the old fallback. Keep a fallback only when unknown values are genuinely part of the contract.

Classes, interfaces, and enums

All three declarations can support an exhaustive when, but they describe different sets. First ask whether variants need distinct payloads, then whether implementations need shared class state or multiple-interface composition.

Prefer an enum for fixed constants with no variant-specific payload. A sealed hierarchy better fits shapes such as Success(value) and Failure(message). Don’t expand a natural constant set into several object declarations solely to obtain when completion.

Declaration location and visibility

Direct subtypes may share a file with their sealed parent or live in other files in the same package and module. Old drafts and tutorials often present “same file” as a permanent restriction. That was an older Kotlin rule and doesn’t apply to the target version.

Subtype visibility must still satisfy ordinary inheritance rules. A sealed class constructor may only be protected or private, and it is protected by default; it can’t be public or internal. A private constructor is useful when every direct subclass must be nested where it can access the parent declaration.

A sealed interface has no constructor and can’t store backing fields. An interface property may require implementations to provide a value or compute one with an accessor, but it can’t own per-instance constructor state. If every variant needs one validated field, a sealed class can often centralize that invariant.

Examples

The three examples progress from payload-bearing states to explicit transitions and multiple-interface classification. Every output was produced by compiling the corresponding file with local Kotlin 2.4.10 and running it on Java 21.

Load states with distinct payloads

The three LoadState variants have different shapes. Loading has no occurrence-specific data, so it is a data object; the other variants use data classes to carry values.

The when has no else, so all three states must explicitly produce a string. In the Ready branch, state is smart-cast and exposes value. Adding a fourth non-sealed variant makes render() report the omission the next time it compiles.

The out modifier makes LoadState covariant . Loading and Failed extend LoadState<Nothing> using the bottom type Nothing. They can therefore appear in a LoadState<String> list without inventing a string value.

Keeping invalid transitions in the model

A sealed state says only that the state set is finite; it doesn’t make every command valid for every state. This reducer returns either Applied or Rejected for every combination instead of hiding expected invalid operations behind exceptions.

sealed interface OrderState {
    data class Created(val id: String) : OrderState
    data class Paid(val id: String, val receipt: String) : OrderState
    data class Cancelled(val id: String) : OrderState
}

sealed interface OrderCommand {
    data class Pay(val receipt: String) : OrderCommand
    data object Cancel : OrderCommand
}

sealed interface Transition {
    data class Applied(val state: OrderState) : Transition
    data class Rejected(val reason: String) : Transition
}

fun reduce(state: OrderState, command: OrderCommand): Transition = when (state) {
    is OrderState.Created -> when (command) {
        is OrderCommand.Pay -> Transition.Applied(
            OrderState.Paid(state.id, command.receipt),
        )
        OrderCommand.Cancel -> Transition.Applied(OrderState.Cancelled(state.id))
    }
    is OrderState.Paid -> Transition.Rejected("paid order is final")
    is OrderState.Cancelled -> Transition.Rejected("cancelled order is final")
}

fun main() {
    val created = OrderState.Created("O-17")
    val paid = reduce(created, OrderCommand.Pay("R-8"))
    val cancelled = reduce(created, OrderCommand.Cancel)

    println(paid)
    println(cancelled)
    println(reduce(OrderState.Cancelled("O-17"), OrderCommand.Cancel))
}

Applied(state=Paid(id=O-17, receipt=R-8))
Applied(state=Cancelled(id=O-17))
Rejected(reason=cancelled order is final)

The outer when covers every order state. Only Created needs to inspect the command, so its inner when covers both commands. This structure makes new states and commands fail at the decision points that need them, while letting terminal states share one rejection rule.

Transition keeps an expected rejection as data. Its caller can use another exhaustive when to decide whether to display, record, or retry it. It doesn’t prevent two concurrent requests from transitioning the same stored order; the state store still needs its own concurrency control and version check.

Cross-classifying with sealed interfaces

NetworkFailure belongs to both the failure set and the retryable set, while ValidationFailure belongs only to the failure set. Sealed interfaces support this cross-classification; a single sealed class hierarchy can’t occupy two class-supertype positions.

sealed interface Failure {
    val message: String
}

sealed interface Retryable {
    val delaySeconds: Int
}

data class NetworkFailure(
    override val message: String,
    override val delaySeconds: Int,
) : Failure, Retryable

data class ValidationFailure(
    val field: String,
    override val message: String,
) : Failure

data object Cancelled : Failure {
    override val message: String = "cancelled"
}

fun describe(failure: Failure): String = when (failure) {
    is NetworkFailure -> "network: ${failure.message}"
    is ValidationFailure -> "${failure.field}: ${failure.message}"
    Cancelled -> failure.message
}

fun retryPlan(value: Retryable): String =
    "retry in ${value.delaySeconds}s"

fun main() {
    val network = NetworkFailure("unreachable", 5)
    println(describe(network))
    println(retryPlan(network))
    println(describe(ValidationFailure("email", "invalid")))
    println(describe(Cancelled))
}

network: unreachable
retry in 5s
email: invalid
cancelled

describe() decides over the whole failure set, while retryPlan() accepts only retryable values. The type relationship itself prevents a validation error from reaching the retry plan. Callers don’t need a Boolean property and a convention about which combinations are valid.

Whether both interfaces should be sealed depends on the extension policy. If an external module needs to define new retryable objects, Retryable should be a regular interface. Don’t close a role that should remain open merely to keep the diagram symmetrical.

Pitfalls

Swallowing new states with else

Fix: list each branch over a genuinely closed hierarchy and remove else. Add a new variant by first allowing compilation to fail, then decide whether every decision point supports, rejects, or transforms it. Don’t apply one placeholder fallback everywhere.

Assuming every descendant is fixed

Fix: inspect the modifier on every direct subtype. Leave leaf variants at the default final, keep grouping nodes sealed, and use open only when the domain truly needs extension at the second level. Treat the corresponding branch as an extension boundary.

Placing direct subtypes across packages or modules

Fix: keep direct variants in the same package and module, and let feature layers compose or wrap those domain values. If deployment boundaries require third-party implementations, switch to a regular interface. Don’t hide the design conflict by moving package declarations or cloning a same-named sealed interface.

Using a singleton for occurrence data

Fix: use a data object for a truly payload-free state and a data class with val properties for a variant that carries per-occurrence data. Write down the payload consumers need before choosing the declaration form. Don’t introduce shared mutable events to avoid allocation.

Treating a sealed hierarchy as a state machine

Fix: match the current state and command in an explicit transition function, returning a typed rejection for invalid transitions. Test the state-command boundary. Add versions, transactions, or single-owner constraints when persistence or concurrent writes are involved.

Sealing an open protocol

Fix: keep open protocols as regular interfaces and design an explicit fallback or capability query on the consuming side. Choose a sealed interface only when one owner controls every direct implementation and adding one should force all handlers to be reviewed.

Further reading

• Kotlin documentation: sealed classes and interfaces
• Kotlin documentation: when expressions and statements
• Kotlin documentation: generic variance
• Kotlin language specification: sealed classes and interfaces
• Kotlin language specification: exhaustive when expressions