Errors & Debugging

Kotlin checks your program twice. First kotlinc, the compiler, reads every file and refuses to produce bytecode if the grammar, the types or the null-safety rules are wrong. Kotlin's compiler catches much more than most languages' — null dereferences, missing when branches, reassigned vals — so a large share of beginner bugs never reach runtime. What is left runs on the JVM, and problems that only appear with real data (an index past the end, text that is not a number, a !! on a null) are thrown as exceptions.

Anatomy of a kotlinc error

Main.kt:3:18: error: unresolved reference 'size' on receiver of type 'String'.
    println(word.size)
                 ^^^^

File, line 3, column 18; the word error (warnings say warning); the message; then the source line with carets under the exact token. The message usually names both what you wrote and the type the compiler saw.

• Fix the first error first. One missing brace or parenthesis can produce a cascade; fix the first, recompile, and many of the rest vanish.
• Read the types in quotes. expected 'Int', actual 'String' or receiver of type 'String?' is usually the whole diagnosis.
• Read warnings too. "Variable is never used", "Condition is always true" and "Unchecked cast" often point at the real bug. Many teams turn on allWarningsAsErrors in Gradle.

Anatomy of a stack trace

Exception in thread "main" java.lang.NumberFormatException: For input string: "x"
	at java.base/java.lang.NumberFormatException.forInputString(Unknown Source)
	at java.base/java.lang.Integer.parseInt(Unknown Source)
	at java.base/java.lang.Integer.parseInt(Unknown Source)
	at MainKt.parse(Main.kt:1)
	at MainKt.total(Main.kt:5)
	at MainKt.main(Main.kt:10)
	at MainKt.main(Main.kt)

The real trace of the program below without its try/catch. Top-level functions in Main.kt compile into a class called MainKt. The last frame, with no line number, is the JVM entry point Kotlin generates around your main.

1. 1
   Read the first line

   The exception class and message are often the whole answer: For input string: "x" means someone converted "x" to a number.

2. 2
   Skip the library frames

   Frames starting with java.base/, kotlin. or a framework package are not your bug. Kotlin's toInt() is a thin wrapper, so the JDK's Integer.parseInt appears here.

3. 3
   Find the first frame in your code

   MainKt.parse(Main.kt:1) is the line of your code that made the failing call. Open it.

4. 4
   Read downward to see how you got there

   Each frame below is the caller: total line 5 called parse, and main line 10 called total. The bad value came in along that path.

5. 5
   Jump to the last "Caused by"

   Frameworks (Spring, Ktor, coroutines) wrap exceptions. The deepest Caused by: section is the original failure. Lambdas show up as frames like MainKt$main$1.invoke.

A stack trace is also an object you can inspect. This program catches the exception and prints only the frames from MainKt — exactly the filter your eyes should apply.

fun parse(s: String): Int = s.toInt()

fun total(items: List<String>): Int {
    var t = 0
    for (s in items) t += parse(s)
    return t
}

fun main() {
    try {
        total(listOf("4", "x"))
    } catch (e: NumberFormatException) {
        println(e)
        for (f in e.stackTrace) {
            if (f.className == "MainKt" && f.lineNumber > 0) {
                println("  at ${f.methodName} line ${f.lineNumber}")
            }
        }
    }
}

java.lang.NumberFormatException: For input string: "x"
  at parse line 1
  at total line 5
  at main line 11

The first four errors are the compiler enforcing Kotlin's type system. Each one is a bug that would crash — or silently misbehave — in a looser language.

fun main() {
    val count: Int = "42"
    println(count + 1)
}

Main.kt:2:20: error: initializer type mismatch: expected 'Int', actual 'String'.
    val count: Int = "42"
                   ^

fun main() {
    val count: Int = "42".toInt()
    println(count + 1)
}

fun main() {
    val word = "kotlin"
    println(word.size)
}

Main.kt:3:18: error: unresolved reference 'size' on receiver of type 'String'.
    println(word.size)
                 ^^^^

fun main() {
    val word = "kotlin"
    println(word.length)
}

fun main() {
    val input: String? = readlnOrNull()
    println(input.trim())
}

Main.kt:3:18: error: only safe (?.) or non-null asserted (!!.) calls are allowed on a nullable receiver of type 'String?'.
    println(input.trim())
                 ^

fun main() {
    val input: String = readlnOrNull() ?: ""
    println(input.trim())
}

fun main() {
    val total = 0
    for (n in listOf(1, 2, 3)) {
        total += n
    }
    println(total)
}

Main.kt:4:9: error: 'val' cannot be reassigned.
        total += n
        ^^^^^

fun main() {
    var total = 0
    for (n in listOf(1, 2, 3)) {
        total += n
    }
    println(total)
}

The next three come from the compiler proving things about every path through your code: that a when handles every case, that a value cannot change between a check and its use, and that a function always returns.

enum class Status { ACTIVE, SUSPENDED, CLOSED }

fun label(s: Status): String = when (s) {
    Status.ACTIVE -> "ok"
    Status.SUSPENDED -> "paused"
}

fun main() = println(label(Status.CLOSED))

Main.kt:3:32: error: 'when' expression must be exhaustive. Add the 'CLOSED' branch or an 'else' branch.
fun label(s: Status): String = when (s) {
                               ^^^^

enum class Status { ACTIVE, SUSPENDED, CLOSED }

fun label(s: Status): String = when (s) {
    Status.ACTIVE -> "ok"
    Status.SUSPENDED -> "paused"
    Status.CLOSED -> "closed"
}

fun main() = println(label(Status.CLOSED))

fun main() {
    var name: String? = "ash"
    val reset = { name = null }
    if (name != null) {
        reset()
        println(name.length)
    }
}

Main.kt:6:17: error: smart cast to 'String' is impossible, because 'name' is a local variable that is mutated in a capturing closure.
        println(name.length)
                ^^^^

fun main() {
    var name: String? = "ash"
    val reset = { name = null }
    val current = name
    if (current != null) {
        reset()
        println(current.length)
    }
}

fun grade(score: Int): String {
    if (score >= 90) return "A"
    else if (score >= 75) return "B"
}

fun main() = println(grade(80))

Main.kt:4:1: error: missing return statement.
}
^

fun grade(score: Int): String = when {
    score >= 90 -> "A"
    score >= 75 -> "B"
    else -> "C"
}

fun main() = println(grade(80))

These compiled cleanly because you told the compiler to trust you — with !!, lateinit or as. At runtime the promise turned out to be false.

fun main() {
    val prices = mapOf("tea" to 20, "coffee" to 35)
    val price = prices["juice"]!!
    println(price * 2)
}

Exception in thread "main" java.lang.NullPointerException
	at MainKt.main(Main.kt:3)
	at MainKt.main(Main.kt)

fun main() {
    val prices = mapOf("tea" to 20, "coffee" to 35)
    val price = prices["juice"] ?: 0
    println(price * 2)
}

class Screen {
    lateinit var title: String

    fun show() = println(title.uppercase())
}

fun main() {
    Screen().show()
}

Exception in thread "main" kotlin.UninitializedPropertyAccessException: lateinit property title has not been initialized
	at Screen.getTitle(Main.kt:2)
	at Screen.show(Main.kt:4)
	at MainKt.main(Main.kt:8)
	at MainKt.main(Main.kt)

class Screen(val title: String) {
    fun show() = println(title.uppercase())
}

fun main() {
    Screen("home").show()
}

fun main() {
    val json: Map<String, Any> = mapOf("name" to "Asha", "age" to "31")
    val age = json["age"] as Int
    println(age + 1)
}

Exception in thread "main" java.lang.ClassCastException: class java.lang.String cannot be cast to class java.lang.Integer (java.lang.String and java.lang.Integer are in module java.base of loader 'bootstrap')
	at MainKt.main(Main.kt:3)
	at MainKt.main(Main.kt)

fun main() {
    val json: Map<String, Any> = mapOf("name" to "Asha", "age" to "31")
    val age = (json["age"] as? String)?.toIntOrNull() ?: 0
    println(age + 1)
}

Most of the runtime errors above crash far from the real mistake. The standard library has three one-liners that make a program fail at the right place with a useful message: require(condition) { message } for bad arguments (throws IllegalArgumentException), check(condition) { message } for bad object state (throws IllegalStateException), and error(message) for code that should be unreachable.

fun withdraw(balance: Int, amount: Int): Int {
    require(amount > 0) { "amount must be positive, was $amount" }
    check(balance >= amount) { "insufficient funds: balance $balance, amount $amount" }
    return balance - amount
}

fun main() {
    println(withdraw(100, 30))
    for (amount in listOf(-5, 500)) {
        try {
            withdraw(100, amount)
        } catch (e: IllegalArgumentException) {
            println("bad input: ${e.message}")
        } catch (e: IllegalStateException) {
            println("bad state: ${e.message}")
        }
    }
}

70
bad input: amount must be positive, was -5
bad state: insufficient funds: balance 100, amount 500

The opposite strategy — for input you expect to be bad sometimes — is not to throw at all. The OrNull functions (toIntOrNull, getOrNull, firstOrNull) return null instead of throwing, and runCatching { } turns any exception into a Result value you can inspect.

fun main() {
    val inputs = listOf("42", "x", "7")

    val results = inputs.map { s -> runCatching { s.toInt() } }
    for (r in results) {
        println(r.fold({ "ok $it" }, { "failed: ${it::class.simpleName}" }))
    }

    println(inputs.mapNotNull { it.toIntOrNull() }.sum())
}

ok 42
failed: NumberFormatException
ok 7
49

The error message tells you where a program failed. When it did not crash but gave the wrong answer, you need to see what it was thinking. Four tools, in the order you will reach for them.

1. The IntelliJ / Android Studio debugger

1. 1
   Set a breakpoint

   Click the gutter next to a line number, then start with Debug (the bug icon) instead of Run. The program pauses when it reaches that line.

2. 2
   Inspect

   The Variables panel shows every local and property. Hover over any expression, or press Alt+F8 (Evaluate Expression) to run Kotlin code against the paused program.

3. 3
   Step

   Step Over (F8) runs the line. Step Into (F7) enters the function called on it. Step Out (Shift+F8) finishes the current function. For chains like list.map { }.filter { }, Smart Step Into (Shift+F7) lets you pick which lambda to enter.

4. 4
   Conditional and exception breakpoints

   Right-click a breakpoint and add a condition such as id == 999. Add a Java Exception breakpoint for NullPointerException to pause at the exact moment one is thrown.

5. 5
   Coroutines

   While paused, the Coroutines tab lists every live coroutine and its state (running, suspended), which is how you find one stuck forever in a receive().

2. Print debugging, done properly

A well-placed print is a legitimate tool. In Kotlin, collection pipelines make it tricky — there is no statement to put a print between — so use onEach { } (runs for every element and passes the collection on) and also { } (runs once with the whole value). Both return their input unchanged, so you can drop them into a chain and delete them later.

fun main() {
    val words = listOf(" Kotlin", "java ", "", "Go")
    val result = words
        .map { it.trim() }
        .onEach { println("after trim: '$it'") }
        .filter { it.length > 2 }
        .also { println("after filter: $it") }
        .map { it.lowercase() }
    println(result)
}

after trim: 'Kotlin'
after trim: 'java'
after trim: ''
after trim: 'Go'
after filter: [Kotlin, java]
[kotlin, java]

3. Logging for code that runs without you

Prints are removed before commit. Logging stays: it has levels (debug detail can be switched off in production), timestamps and thread names, and it goes to files or a log platform. Kotlin projects use SLF4J with Logback, often through the small kotlin-logging wrapper, whose lambda messages are only built when that level is enabled.

import io.github.oshai.kotlinlogging.KotlinLogging

private val log = KotlinLogging.logger {}

class OrderService(private val payments: Payments) {
    fun place(order: Order) {
        log.debug { "placing order ${order.id} with ${order.items.size} items" }  // built only if DEBUG is on
        try {
            payments.charge(order)
            log.info { "order ${order.id} placed" }
        } catch (e: PaymentException) {
            log.error(e) { "payment failed for order ${order.id}" }   // e first: the stack trace is logged
            throw e
        }
    }
}

Always pass the exception object to the logger. Logging only e.message throws away the stack trace you will need at 2 a.m.

4. Let tools find bugs before you run anything

• IntelliJ inspections: yellow highlights for unused values, always-true conditions and redundant !!. Alt+Enter offers the fix.
• detekt: static analysis for Kotlin — complexity, swallowed exceptions, magic numbers. Runs in Gradle and CI.
• ktlint: formatting and style, so reviews talk about logic instead of spaces.
• Kotlin scratch files and the REPL: in IntelliJ, File → New → Scratch File → Kotlin evaluates code as you type — the fastest way to answer "what does "a,b,,c".split(",") return?"

Compile error

A problem kotlinc finds before anything runs; no bytecode is produced.

Runtime exception

An exception thrown while the program runs, such as NullPointerException or NumberFormatException.

Stack trace

The exception type, message and the chain of function calls (frames) that led to it, newest first.

MainKt

The JVM class Kotlin generates for the top-level functions in Main.kt; it names those frames in a stack trace.

Caused by

A wrapped original exception inside a stack trace; the deepest one is the root cause.

require / check

Standard-library preconditions that throw IllegalArgumentException / IllegalStateException with your message.

runCatching

Runs a block and returns a Result holding either the value or the exception.

Breakpoint

A line where the debugger pauses the program so you can inspect variables.

detekt

A static-analysis tool for Kotlin that reports code smells and likely bugs.