Null safety

What it is and why it exists

Kotlin null safety makes absence part of static type information. A plain String cannot hold null; the nullable type String? can hold either a string or null. A function signature therefore tells callers whether absence belongs to the contract, without relying on a comment or waiting until dereference to find out.

This design moves many null-pointer errors to compile time. If a receiver is String?, the compiler rejects a direct read of length; code must first prove the value is non-null, use a safe call, or explicitly accept the risk of a not-null assertion. It reduces unchecked dereferences, not every possible NullPointerException.

You meet nullable types when database columns, JSON fields, lookup results, optional configuration, or Java APIs may not supply a value. The key design question is not how quickly to remove the question mark, but what null means at this boundary: a valid omission, not found, invalid data, or a broken program state. Those meanings call for different handling.

Null safety does not validate empty strings, negative numbers, stale values, or invariants between objects. String proves only that the reference is non-null, not that the text is non-blank. Validate content before entering the domain layer, and let domain types store valid states whenever possible.

How it works

Two neighboring types

For a non-null type T, T? is its nullable version with the additional value null. A non-null value can be assigned to the corresponding nullable variable, so a String value works where String? is required; assignment in the other direction must handle null first. Repeating the question mark adds no new meaning, and Kotlin has no separate T?? level.

Nullability applies to the type immediately beside it. List<String>? means the list may be missing but every element of a present list is a non-null string; List<String?> means the list exists but its elements may be missing; List<String?>? permits both. Function types also depend on parentheses: ((String) -> Int)? is a nullable function value, while (String) -> Int? is a present function that may return null.

An API should expose T? only when absence has a real meaning. A lookup can reasonably return User? when no record exists, but if an authenticated request context still models its required user as User?, every downstream step must handle a state that should be impossible. The sooner a boundary normalizes input into a valid non-null value, the smaller the state space of later code.

Checks and smart casts

An explicit check is the most direct way to narrow a type. In the true branch of if (name != null), the compiler can treat a stable name as String; if the null branch has already returned or thrown, the path after the check can also use the non-null type. This control-flow-proven narrowing is a smart cast , with no forced runtime cast in source.

A smart cast requires the compiler to guarantee that the value cannot change between the check and its use. A local val usually qualifies, and a local var may qualify when it is not modified in between or captured by a lambda that changes it. Mutable properties do not smart-cast because other code or a custom accessor could produce a different result between two reads.

For a mutable property, reading one local snapshot is usually the right repair. val email = account.email fixes the reference observed by this operation, and a non-null check on email can then dominate its use. Bypassing the compiler with account.email!! reads the property again and turns a race or changing custom getter into a runtime crash.

An is check can prove both type and non-nullness. Once value is String succeeds, value is a non-null String. If failed conversion is an ordinary branch, the safe cast value as? String returns String?; a plain as String throws ClassCastException on a type mismatch and is not null handling.

Expressions for absence

The safe call ?. reads a property or invokes a function when its receiver is non-null; otherwise the whole expression returns null. The chain order?.customer?.address?.city stops at the first null receiver. Its result usually remains nullable because the chain answers whether it can obtain a value, not what should happen when it cannot.

A safe call can also appear on the left of an assignment. If any receiver in account?.address?.city = computeCity() is null, Kotlin skips both the assignment and evaluation of computeCity() on the right. That matters when the right-hand expression logs, counts, or performs I/O; this is more than shorthand for property access.

The Elvis operator ?: returns its left side when non-null and evaluates its right side only otherwise. The right side can be a default, return, or throw, because Kotlin permits them in expression position. val user = lookup(id) ?: return NotFound cleanly ends the missing branch at function entry and leaves user non-null afterward.

value?.let { use(it) } calls the lambda only when value is non-null and returns the lambda result. That is useful for a small transformation, but it is not safer than an ordinary if; if use itself has a nullable result, the final null cannot distinguish a missing receiver from failed transformation. Use explicit branches or a typed result when the reason matters.

The not-null assertion !! treats a nullable expression as non-null and throws NullPointerException when its value is null. It can make a violated test precondition fail immediately, but on a production path it usually means an invariant was not expressed at the boundary. Prefer requireNotNull for a caller error, checkNotNull for an object-state error, or Elvis with a domain result.

The common tools have these semantics:

Absence policy is an API contract

The same null may require different return shapes in different APIs. When a cache lookup defines null as a miss, Entry? is enough; when command execution must distinguish rejection, conflict, and dependency failure, a nullable return loses information. Type design should first preserve the differences that make callers act differently, then choose syntax.

Use this sequence when deciding how to handle a nullable input:

1. Decide whether absence is valid; if not, reject it as close to the input as possible.
2. Decide whether valid absence has only one meaning; use plain T? only when it does.
3. Decide whether the caller needs the reason; return a sealed result or throw a contractually specified exception when it does.
4. Decide whether a default is fully equivalent to supplying that value explicitly; do not erase provenance with Elvis when it is not.

Common boundaries map to different shapes:

A default is itself business data. Writing a missing timeout as timeout ?: 30 promises that “not configured” and “explicitly configured as 30” are equivalent for every later behavior. If the system must show inheritance, write configuration back, or audit changes, preserve whether the value was absent.

requireNotNull(value) throws IllegalArgumentException on failure and suits a bad caller argument; checkNotNull(value) throws IllegalStateException and suits the receiver or current execution phase. Both return a non-null value, so they can initialize a local directly. They communicate responsibility better than !!, but neither belongs on an ordinary not-found path.

A public function must also make its contract legible to Java callers. A String? parameter says the function must accept null from Java, while a String parameter generates a non-null check at the Kotlin entry point. A safe call inside the implementation cannot repair the wrong signature because compatibility and caller code generation see the signature first.

Equality and nullable booleans

Kotlin’s structural equality operator == safely compares nullable references. left == right handles the case where both sides are null without a preceding safe call, and != is equally null-safe. Referential equality === asks whether two references identify the same object and also permits null on either side, but it answers an identity question rather than value equality.

Boolean? has three states, while a condition requires Boolean. flag == true succeeds only for an explicit true, merging false and null into the other branch; flag ?: false collapses the same two states. That is correct only when the business really defines “unknown” as “no.”

Use when (flag) with separate true, false, and null branches when all three states matter. This does more than avoid a compile error: later logs, metrics, or user messages can still identify the unknown source. Mechanically changing Boolean? to Boolean and filling in false usually discards information too early in the data model.

Nullable receiver extensions still run

An extension function can declare a nullable receiver, such as fun String?.display(): String. Calling name.display() runs the body even when name is null, and this remains String? inside. This design fits a stable missing representation centralized for one type.

Writing name?.display() at the call site changes the semantics: when the receiver is null, the safe call skips the extension body and produces null. If display() was meant to turn null into placeholder text, the extra ?. bypasses that fallback. Review both the extension receiver type and the call operator.

A nullable receiver extension should not conceal a business decision that depends on context. A missing name may need a fixed marker in logs, localized text in the UI, and preserved null in persistence. Those policies belong at their respective boundaries, not inside one global string extension.

Test at least four inputs for this kind of extension: null, empty text, blank text, and an ordinary value. Also call both value.extension() and value?.extension(), because they take different paths when the receiver is null. Testing only a non-null value misses the API’s most distinctive contract.

Examples

The four programs progress from reading a nullable value to boundary normalization and a generic collection. Each file was compiled with Kotlin 2.4.10 and run on JRE 21; every following output block comes from that execution.

Narrow once, continue with a non-null value

The first program keeps its nullable input at the entrance to label. Elvis returns early when the profile is absent; after that, the local current is a non-null Profile, and only the genuinely optional bio keeps a safe-call chain.

takeIf also turns a blank bio into null, so ?: "no bio" handles both original absence and failed validation. That is appropriate when the two cases mean the same thing to the business; if the UI must distinguish never supplied from whitespace only, preserve separate branches.

The function returns String, so its callers do not keep handling a nullable result. That signature states that label fully resolves missing input instead of passing the decision to the next layer.

Safe call and Elvis both short-circuit

The second program demonstrates two lazy behaviors. displayCity computes a default city only when the safe-call chain produces null; a safe assignment on the left also skips its right side when no receiver exists.

data class Address(var city: String?)
data class Account(val address: Address?)

fun defaultCity(): String {
    println("default computed")
    return "unknown"
}

fun displayCity(account: Account?): String =
    account?.address?.city ?: defaultCity()

fun main() {
    val known = Account(Address("Lyon"))
    val absent: Account? = null

    println(displayCity(known))
    println(displayCity(absent))

    var writes = 0
    absent?.address?.city = run {
        writes += 1
        "ignored"
    }
    known.address?.city = "Paris"

    println(known.address?.city)
    println(writes)
}

Lyon
default computed
unknown
Paris
0

Reading the known city does not print default computed, proving that the Elvis right side was not evaluated eagerly. The final writes value of 0 proves that the safe assignment skipped the entire run on its right when the receiver was absent.

Short-circuiting avoids useless work, but it can also hide an expected side effect. If an audit event must be written whether or not the object exists, place that operation outside the safe call and record the failure reason explicitly.

Preserve failure reasons at the boundary

The third program models conversion from a permissive external record into a domain object. Raw fields stay nullable or have an unknown type, while the parser uses a safe cast, content validation, and early returns to construct an Order with only valid non-null properties.

data class RawOrder(val id: String?, val cents: Int?, val customer: Any?)
data class Order(val id: String, val cents: Int, val customer: String)

sealed interface ParseResult {
    data class Valid(val order: Order) : ParseResult
    data class Invalid(val reason: String) : ParseResult
}

fun parseOrder(row: RawOrder): ParseResult {
    val id = row.id?.trim()?.takeIf { it.isNotEmpty() }
        ?: return ParseResult.Invalid("missing id")
    val cents = row.cents?.takeIf { it >= 0 }
        ?: return ParseResult.Invalid("invalid cents")
    val customer = (row.customer as? String)
        ?.trim()
        ?.takeIf { it.isNotEmpty() }
        ?: return ParseResult.Invalid("invalid customer")

    return ParseResult.Valid(Order(id, cents, customer))
}

fun main() {
    val rows = listOf(
        RawOrder(" A-7 ", 950, " Ada "),
        RawOrder("B-2", null, "Lin"),
        RawOrder("C-3", 400, 42),
    )

    rows.map(::parseOrder).forEach(::println)
}

Valid(order=Order(id=A-7, cents=950, customer=Ada))
Invalid(reason=invalid cents)
Invalid(reason=invalid customer)

There is no !!: each local is narrowed by an early Elvis return. The success branch can carry only a complete Order, while the failure branch preserves a field-specific reason; both are easier to use than a half-built object with several nullable properties.

as? String puts a type mismatch on the ordinary failure path instead of throwing ClassCastException. It does not validate string contents, so the later trim and takeIf remain necessary.

Distinguish nullable collections from nullable elements

The fourth program adds the generic bound T : Any, so a successful result cannot contain null. An absent tag list is defined as an empty list, but a present list with a null element is treated as corrupt data and reports the index.

fun <T : Any> requireAll(values: List<T?>): List<T> =
    values.mapIndexed { index, value ->
        requireNotNull(value) { "value at index $index is null" }
    }

fun normalizedTags(raw: List<String?>?): List<String> {
    val tags = raw ?: return emptyList()
    return requireAll(tags).map(String::trim)
}

fun main() {
    println(normalizedTags(listOf("red", "blue")))

    val message = runCatching {
        normalizedTags(listOf("red", null, "blue"))
    }.exceptionOrNull()?.message
    println(message)

    println(normalizedTags(null).size)
}

[red, blue]
value at index 1 is null
0

Replacing this with filterNotNull() would silently delete the corrupt element and change the output length. Do that only when discarding elements is the contract; when positions or cardinality matter, validate and report the index instead.

raw ?: return emptyList() is an explicit business decision, not a null-safety rule. If a missing list and an empty list mean different things, preserve that difference in the return type, perhaps with a sealed result, instead of mechanically calling orEmpty().

Pitfalls

Fix: First classify null as a caller error, an object-state error, or a normal branch, then use requireNotNull, checkNotNull, or an Elvis return respectively. !! communicates clearly only when the crash itself is part of a test assertion.

Fix: Use safe calls for genuinely optional tail fields; validate required intermediate objects one by one at the boundary and return a specific error. During review, list every point in the chain that can produce null and confirm that all points truly have the same business meaning.

Fix: Read the property into a local val, then check and use that snapshot. If the operation must be atomic against the latest value, a local snapshot is still insufficient; put a lock or an atomic operation inside the state owner.

Fix: Define the meaning of null separately for the container and its elements, then test cardinality, order, and indexes. Reject corrupt input; filter only when product rules explicitly permit ignoring missing items.

Fix: Inspect Java nullability annotations at the interoperability boundary, assign unannotated or untrusted results to an explicit T?, and normalize immediately. Do not substitute one passing test, an example in documentation, or a generator’s guess for real annotations and boundary tests.

Further reading

• Kotlin documentation source: Null safety
• Kotlin documentation: Type checks and casts
• Kotlin documentation: Nullability annotations in Java interoperability
• Kotlin documentation: Definitely non-nullable types