Skip to main content
Back to Library
kotlin in depth advanced patterns for java engineers

Null Safety Internals — Beyond the Question Mark

9 min read Chapter 2 of 21

Null Safety Internals — Beyond the Question Mark

You know that String? means nullable and String means non-null. But what actually happens when the compiler enforces this? The answer isn’t an annotation processor, a runtime check library, or a linter. It’s a compiler-level control flow analysis that tracks nullability state through every branch, assignment, and return path of your code — and it happens entirely at compile time.

Control Flow Analysis: How the Compiler Thinks About Null

The Kotlin compiler builds a control flow graph (CFG) for each function body. At every point in that graph, the compiler maintains a set of data flow facts about each variable — including whether it has been proven non-null.

Consider this function:

fun processName(name: String?) {
    // Point A: name is String? — could be null

    if (name != null) {
        // Point B: name is narrowed to String — compiler proved non-null
        println(name.length)
    }

    // Point C: name is String? again — the if-branch proof expired
}

The compiler doesn’t track this through a single flag. It builds a lattice of types at each program point. At Point B, the variable name has been narrowed from String? to String through the null check. This narrowing propagates forward through the control flow graph until a merge point (Point C) where the if-branch and the else-branch (implicit fall-through) converge. Since the else-branch didn’t prove non-nullability, the merged type reverts to String?.

Early returns make this more interesting:

fun processName2(name: String?) {
    if (name == null) return
    // Everything below: name is String
    // because the only way to reach here is if name != null
    println(name.length)
    println(name.uppercase())
}

The compiler recognizes that return, throw, and continue/break terminate a control flow path. If the null case terminates, the remaining code only executes in the non-null case.

Bytecode: What ?. and ?: Actually Compile To

The safe call operator ?. and the elvis operator ?: look like special syntax, but they compile to straightforward conditional jumps. Examine this:

fun safeCallDemo(name: String?): Int {
    return name?.length ?: 0
}

Compile and decompile:

kotlinc SafeCall.kt -include-runtime -d safecall.jar
javap -p -c SafeCallKt.class

The decompiled Java equivalent is:

// What the compiler generates (conceptual decompilation)
public static int safeCallDemo(String name) {
    int var10000;
    if (name != null) {
        var10000 = name.length();
    } else {
        var10000 = 0;
    }
    return var10000;
}

There’s no runtime wrapper, no Optional<T>, no method dispatch overhead. The safe call compiles to null check + conditional branch. This is critical to understand: Kotlin’s null safety has zero runtime cost for safe calls. Compare this to Java’s Optional<T>, which allocates a wrapper object on every call.

Here’s a chained safe call:

fun cityName(person: Person?): String? {
    return person?.address?.city?.name
}

This compiles to nested null checks:

// Decompiled equivalent
public static String cityName(Person person) {
    if (person == null) return null;
    Address address = person.getAddress();
    if (address == null) return null;
    City city = address.getCity();
    if (city == null) return null;
    return city.getName();
}

Each ?. is a null check that short-circuits to null on failure. No intermediate objects, no monadic chains — just branches.

Platform Types: The Java Interop Danger Zone

Kotlin can’t know the nullability of types coming from Java code. Java’s @Nullable and @NonNull annotations exist, but they’re not universal, not standardized, and most libraries don’t use them consistently. Kotlin handles this through platform types, denoted internally as T!.

You’ll never write T! yourself — it’s not valid Kotlin syntax. But it appears in error messages and IDE hints when you call Java code:

// Java class
public class JavaUser {
    public String getName() { return name; } // No nullability annotation
}
// Kotlin calling Java
fun greetJavaUser(user: JavaUser) {
    // user.name has type String! (platform type)
    // The compiler lets you treat it as EITHER String or String?

    // This compiles — treating as non-null
    val len: Int = user.name.length

    // This also compiles — treating as nullable
    val len2: Int? = user.name?.length
}

The danger: if you treat a platform type as non-null and the Java method returns null, you get a runtime NullPointerException — but with a twist. Kotlin inserts an intrinsic null check at the assignment point:

fun riskyCall(user: JavaUser) {
    val name: String = user.name  // Kotlin inserts: Intrinsics.checkNotNull(name)
    // If user.getName() returns null, you get:
    // java.lang.NullPointerException: user.name must not be null
}

Verify by decompiling:

javap -c -p RiskyCallKt.class

You’ll see a call to kotlin.jvm.internal.Intrinsics.checkNotNull() right after the method call. This gives you a clear error message pointing to the exact variable, rather than a random NPE three methods later. But it’s still a runtime failure — the compiler can’t save you here.

Defensive strategy for Java interop:

fun safeJavaInterop(user: JavaUser) {
    // Strategy 1: Explicitly declare as nullable and handle
    val name: String? = user.name
    println(name?.length ?: "unknown")

    // Strategy 2: Use requireNotNull with a meaningful message
    val verifiedName: String = requireNotNull(user.name) {
        "JavaUser.getName() returned null for user: $user"
    }
    println(verifiedName.length)
}

Java Developer Trap: When migrating a Java codebase to Kotlin, the most dangerous moment is the boundary between Java and Kotlin code. Every Java method you call returns a platform type unless annotated. Treat all Java return values as nullable (Type?) until you’ve verified the contract. The compiler won’t force you to — but production NullPointerException will.

Smart Casts: When They Work and When They Break

Smart casts are control-flow-sensitive type narrowing. After an is check or a null check, the compiler narrows the variable’s type for the remainder of that control flow path.

fun smartCastShowcase(value: Any?) {
    // Null check → narrows from Any? to Any
    if (value == null) return

    // is check → narrows from Any to String
    if (value is String) {
        println(value.length)      // Smart cast to String
        println(value.uppercase()) // Still String
    }

    // Combined in when
    when (value) {
        is Int -> println(value * 2)          // Smart cast to Int
        is String -> println(value.reversed()) // Smart cast to String
        is List<*> -> println(value.size)      // Smart cast to List<*>
    }
}

But smart casts fail in specific, well-defined situations. Understanding why they fail reveals the compiler’s safety guarantees.

Failure Case 1: Mutable Properties (var)

class Container {
    var value: Any? = null
}

fun brokenSmartCast(container: Container) {
    if (container.value is String) {
        // ERROR: Smart cast to 'String' is impossible because
        // 'container.value' is a mutable property that could
        // have been changed by this time

        // println(container.value.length)  // Won't compile
    }
}

The compiler refuses because another thread could modify container.value between the is check and the usage. Even in single-threaded code, the compiler can’t prove that no concurrent modification occurs. The fix:

fun fixedSmartCast(container: Container) {
    val captured = container.value  // Capture to local val
    if (captured is String) {
        println(captured.length)  // Works — local val can't be modified
    }
}

Failure Case 2: Custom Getters

class Tricky {
    val value: Any?
        get() = if (Random.nextBoolean()) "hello" else null
}

fun trickySmartCast(t: Tricky) {
    if (t.value is String) {
        // ERROR: Smart cast impossible — property has custom getter
        // Each access to t.value could return a different result

        // println(t.value.length)  // Won't compile
    }
}

A custom getter is a function call, and the compiler can’t guarantee idempotency. Each call to t.value might return a different result. Same fix — capture to a local val.

Failure Case 3: Delegated Properties

class Holder {
    val value: Any? by lazy { computeExpensiveValue() }
}

Delegated properties use getValue() calls under the hood. The compiler treats them like custom getters — no smart cast guarantee.

Null Safety Compiler Flow

The !! Operator: When It’s Legitimate

The not-null assertion operator (!!) is widely misunderstood. It’s not a code smell by default — it’s a tool with a specific purpose: “I have information the compiler doesn’t.”

Legitimate uses of !!:

// 1. After external validation that the compiler can't see
fun processValidated(data: Map<String, Any?>) {
    // Framework guarantees "name" exists and is non-null after validation
    // The type system can't express this guarantee
    val name = data["name"]!! as String
}

// 2. In tests, where a clear NPE is the desired failure mode
@Test
fun `user should have address after registration`() {
    val user = registerUser("[email protected]")
    val address = user.address!!  // NPE here means the test found a bug
    assertEquals("Default City", address.city)
}

// 3. Lateinit alternative for non-null types (rare)
// When lateinit can't be used (e.g., primitive types)
private var _count: Int? = null
val count: Int get() = _count!!

Illegitimate uses — refactor instead:

// BAD: Lazy handling of platform types
fun bad(javaObject: JavaThing) {
    val name = javaObject.name!!  // Will crash if null — no safety
}

// GOOD: Handle the null case
fun good(javaObject: JavaThing) {
    val name = javaObject.name ?: throw IllegalStateException(
        "Expected non-null name from JavaThing: $javaObject"
    )
}

The difference: !! throws a generic NullPointerException with no message. The explicit throw gives you an IllegalStateException with context. In a production stack trace at 3 AM, that context matters.

The Null Safety Guarantee in Practice

The compiler’s null safety works through three mechanisms in concert:

  1. Type-level encoding: T and T? are distinct types. You can’t assign T? to T without a check.
  2. Control flow analysis: The compiler narrows types through checks, early returns, and when branches.
  3. Intrinsic checks at boundaries: When you assign a platform type to a non-null variable, the compiler inserts runtime checks with descriptive error messages.

The result: NullPointerException in pure Kotlin code can only occur through three paths — !! assertions, platform type mismatches, or lateinit access before initialization. Every other null-related bug is caught at compile time. For Java developers accustomed to defensive null checking scattered throughout the codebase, this is a fundamental shift. The compiler does the work.

// Pure Kotlin code: the compiler guarantees no NPE from these operations
fun safePipeline(input: String): Result {
    val parsed = parse(input)           // Returns ParsedData (non-null)
    val validated = validate(parsed)     // Returns ValidatedData (non-null)
    val result = transform(validated)    // Returns Result (non-null)
    return result                        // Guaranteed non-null
}

// The only way this throws NPE is if parse(), validate(), or transform()
// internally use !! or call Java code unsafely

This guarantee flows upward through your call stack. As long as your Kotlin-to-Java boundaries are handled defensively, null safety is compositional — safe functions compose into safe programs.