Errors & Debugging

Scala programs fail in two very different ways. A compile error stops the program before it starts: the compiler has proved something is wrong, points at the exact line and column, and nothing runs. A runtime exception happens while the program is running: the code was valid, but some value — an empty list, a null from Java, bad input — made an operation impossible, and the JVM prints a stack trace. Scala's type system is designed to move as many bugs as possible from the second group into the first.

Anatomy of a Scala 3 compiler message

-- [E007] Type Mismatch Error: Main.scala:2:17
2 |  val age: Int = "42"
  |                 ^^^^
  |                 Found:    ("42" : String)
  |                 Required: Int
  |
  | longer explanation available when compiling with `-explain`
1 error found
Compilation failed

The exact output of compiling a two-line program that assigns a String to an Int.

scala compile -explain Main.scala
# in sbt, add to build.sbt:  scalacOptions += "-explain"

Ask the compiler to explain every error in detail.

A stack trace is the list of method calls that were in progress when the exception was thrown. The first line names the exception and its message. Each at line below is one call, newest first: the top is where the exception was thrown, the bottom is where the program started. Reading it is a skill, and the trick is to skip the library lines and find the frames from your file.

Exception in thread "main" java.lang.NumberFormatException: For input string: "two"
	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 scala.collection.StringOps$.toInt$extension(StringOps.scala:971)
	at Main$package$.parseQty(Main.scala:3)
	at Main$package$.totalQty$$anonfun$1(Main.scala:5)
	at scala.collection.immutable.List.map(List.scala:248)
	at Main$package$.totalQty(Main.scala:5)
	at Main$package$.run(Main.scala:9)
	at run.main(Main.scala:7)

Real output of a program whose second order has the quantity "two".

1. 1
   Read the first line

   The exception type and message are the most useful part: NumberFormatException: For input string: "two" already tells you a string that is not a number was parsed.

2. 2
   Read the stack bottom-up to see the story

   run.main started the program, run (line 9) called totalQty, which called map, whose lambda called parseQty (line 3). That is the path from your entry point to the crash.

3. 3
   Find the top-most frame in your file

   Skip java.base/... and scala.collection... frames — the bug is almost never in the JDK. The highest Main.scala line, parseQty(Main.scala:3), is where your code handed over the bad value.

4. 4
   Decode the Scala names

   Top-level definitions live in a class called Main$package$. $$anonfun$1 is a lambda. $extension is an extension method. A @main def run is launched by a generated class named run.

5. 5
   Look for "Caused by:"

   When a library wraps an exception, the trace continues with Caused by: .... The last "Caused by" is usually the real root cause. Spark and database drivers do this a lot.

A stack trace is just data on the exception object. You can inspect it yourself — handy in a log line — by filtering getStackTrace to frames from your own file:

case class Order(id: Int, qty: String)

def parseQty(o: Order): Int = o.qty.toInt

def totalQty(orders: List[Order]): Int = orders.map(parseQty).sum

@main def run(): Unit =
  val orders = List(Order(1, "3"), Order(2, "two"))
  try println(totalQty(orders))
  catch
    case e: NumberFormatException =>
      println(s"${e.getClass.getSimpleName}: ${e.getMessage}")
      e.getStackTrace
        .filter(f => f.getFileName != null && f.getFileName.equalsIgnoreCase("Main.scala"))
        .foreach(f => println(s"  at ${f.getMethodName} (line ${f.getLineNumber})"))

NumberFormatException: For input string: "two"
  at parseQty (line 3)
  at totalQty$$anonfun$1 (line 5)
  at totalQty (line 5)
  at run (line 9)
  at main (line 7)

These eight are the compile errors that fill a Scala beginner's first month. Every message below is real output from Scala 3.9. Each one is the compiler catching a bug that would otherwise have reached a user.

@main def run(): Unit =
  val age: Int = "42"
  println(age + 1)

-- [E007] Type Mismatch Error: Main.scala:2:17
2 |  val age: Int = "42"
  |                 ^^^^
  |                 Found:    ("42" : String)
  |                 Required: Int
1 error found
Compilation failed

@main def run(): Unit =
  val age: Int = "42".toInt
  println(age + 1)

@main def run(): Unit =
  val total = 10
  println(totl * 2)

-- [E006] Not Found Error: Main.scala:3:10
3 |  println(totl * 2)
  |          ^^^^
  |          Not found: totl - did you mean total?
1 error found
Compilation failed

@main def run(): Unit =
  val total = 10
  println(total * 2)

case class User(name: String, email: String)

@main def run(): Unit =
  val u = User("Asha", "[email protected]")
  println(u.emial)

-- [E008] Not Found Error: Main.scala:5:12
5 |  println(u.emial)
  |          ^^^^^^^
  |          value emial is not a member of User - did you mean u.email?
1 error found
Compilation failed

case class User(name: String, email: String)

@main def run(): Unit =
  val u = User("Asha", "[email protected]")
  println(u.email)

class Clock:
  def now(): Long = 42L

@main def run(): Unit =
  val c = Clock()
  val t: Long = c.now
  println(t)

-- [E100] Syntax Error: Main.scala:6:18
6 |  val t: Long = c.now
  |                ^^^^^
  |                method now in class Clock must be called with () argument
1 error found
Compilation failed

class Clock:
  def now(): Long = 42L

@main def run(): Unit =
  val c = Clock()
  val t: Long = c.now()
  println(t)

@main def run(): Unit =
  val count = 0
  count = count + 1
  println(count)

-- [E052] Type Error: Main.scala:3:8
3 |  count = count + 1
  |  ^^^^^^^^^^^^^^^^^
  |  Reassignment to val count
1 error found
Compilation failed

@main def run(): Unit =
  var count = 0
  count = count + 1
  println(count)

def factorial(n: Int) =
  if n <= 1 then 1 else n * factorial(n - 1)

@main def run(): Unit =
  println(factorial(5))

-- [E044] Cyclic Error: Main.scala:2:28
2 |  if n <= 1 then 1 else n * factorial(n - 1)
  |                            ^
  |                Overloaded or recursive method factorial needs return type
  |
  |                 Run with -explain-cyclic for more details.
1 error found
Compilation failed

def factorial(n: Int): Int =
  if n <= 1 then 1 else n * factorial(n - 1)

@main def run(): Unit =
  println(factorial(5))

@main def run(): Unit =
  val scores = List(70, 85, 92)
  for s <- scores do
      val grade = if s >= 90 then "A" else "B"
    println(s"$s -> $grade")

-- Error: Main.scala:5:4
5 |    println(s"$s -> $grade")
  |    ^
  |The start of this line does not match any of the previous indentation widths.
  |Indentation width of current line : 4 spaces
  |This falls between previous widths: 2 spaces and 6 spaces
-- [E006] Not Found Error: Main.scala:5:15
5 |    println(s"$s -> $grade")
  |               ^
  |               Not found: s
-- [E006] Not Found Error: Main.scala:5:21
5 |    println(s"$s -> $grade")
  |                     ^^^^^
  |                     Not found: grade
3 errors found
Compilation failed

@main def run(): Unit =
  val scores = List(70, 85, 92)
  for s <- scores do
    val grade = if s >= 90 then "A" else "B"
    println(s"$s -> $grade")

case class Employee(name: String, salary: Int)

def highestPaid[A: Ordering](xs: List[A]): A = xs.max

@main def run(): Unit =
  val staff = List(Employee("Ravi", 50), Employee("Asha", 70))
  println(highestPaid(staff))

-- [E172] Type Error: Main.scala:7:28
7 |  println(highestPaid(staff))
  |                            ^
  |No given instance of type Ordering[Employee] was found for a context parameter of method highestPaid.
  |I found:
  |
  |    scala.math.Ordering.ordered[Employee](
  |      /* missing */summon[scala.math.Ordering.AsComparable[Employee]])
  |
  |But no implicit values were found that match type scala.math.Ordering.AsComparable[Employee].
  |
  |The following import might make progress towards fixing the problem:
  |
  |  import scala.math.Ordered.orderingToOrdered
  |
1 error found
Compilation failed

case class Employee(name: String, salary: Int)

given Ordering[Employee] = Ordering.by(_.salary)

def highestPaid[A: Ordering](xs: List[A]): A = xs.max

@main def run(): Unit =
  val staff = List(Employee("Ravi", 50), Employee("Asha", 70))
  println(highestPaid(staff))

A match that misses a case is the one bug Scala reports as a warning rather than an error: the program still compiles and runs. If the missing case ever arrives, it crashes with MatchError. The two cards below are the same bug seen at compile time and at runtime. Treat the warning as an error — many teams make it one with -Werror.

enum Status:
  case Active, Suspended, Closed

def label(s: Status): String = s match
  case Status.Active    => "active"
  case Status.Suspended => "on hold"

@main def run(): Unit =
  println(label(Status.Active))

-- [E029] Pattern Match Exhaustivity Warning: Main.scala:4:31
4 |def label(s: Status): String = s match
  |                               ^
  |                               match may not be exhaustive.
  |
  |                               It would fail on pattern case: Closed
1 warning found
active

enum Status:
  case Active, Suspended, Closed

def label(s: Status): String = s match
  case Status.Active    => "active"
  case Status.Suspended => "on hold"
  case Status.Closed    => "closed"

@main def run(): Unit =
  println(label(Status.Active))

def describe(code: Int): String = code match
  case 200 => "OK"
  case 404 => "Not Found"

@main def run(): Unit =
  println(describe(200))
  println(describe(500))

OK
Exception in thread "main" scala.MatchError: 500 (of class java.lang.Integer)
	at Main$package$.describe(Main.scala:3)
	at Main$package$.run(Main.scala:7)
	at run.main(Main.scala:5)

def describe(code: Int): String = code match
  case 200   => "OK"
  case 404   => "Not Found"
  case other => s"HTTP $other"

@main def run(): Unit =
  println(describe(200))
  println(describe(500))

Each of these compiles cleanly and crashes when it runs. Four of the five come from the same root cause: code that assumes a value is there, is the right type, or is a number, without checking. The fixes use the tools from Module 08.

@main def run(): Unit =
  val queue = List.empty[String]
  val next = queue.head
  println(s"processing $next")

Exception in thread "main" java.util.NoSuchElementException: head of empty list
	at scala.collection.immutable.Nil$.head(List.scala:664)
	at scala.collection.immutable.Nil$.head(List.scala:664)
	at Main$package$.run(Main.scala:3)
	at run.main(Main.scala:1)

@main def run(): Unit =
  val queue = List.empty[String]
  queue.headOption match
    case Some(next) => println(s"processing $next")
    case None       => println("queue is empty")

@main def run(): Unit =
  val mode: String = System.getProperty("app.mode")
  println(mode.toUpperCase)

Exception in thread "main" java.lang.NullPointerException: Cannot invoke "String.toUpperCase()" because "mode" is null
	at Main$package$.run(Main.scala:3)
	at run.main(Main.scala:1)

@main def run(): Unit =
  val mode: String = Option(System.getProperty("app.mode")).getOrElse("dev")
  println(mode.toUpperCase)

@main def run(): Unit =
  val values: List[Any] = List(1, "two", 3)
  val total = values.map(_.asInstanceOf[Int]).sum
  println(total)

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 scala.runtime.BoxesRunTime.unboxToInt(BoxesRunTime.java:100)
	at Main$package$.$anonfun$1(Main.scala:3)
	at scala.collection.immutable.List.map(List.scala:248)
	at Main$package$.run(Main.scala:3)
	at run.main(Main.scala:1)

@main def run(): Unit =
  val values: List[Any] = List(1, "two", 3)
  val total = values.collect { case n: Int => n }.sum
  println(total)

@main def run(): Unit =
  val raw = List("10", "20", "3O")
  val numbers = raw.map(_.toInt)
  println(numbers.sum)

Exception in thread "main" java.lang.NumberFormatException: For input string: "3O"
	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 scala.collection.StringOps$.toInt$extension(StringOps.scala:971)
	at Main$package$.$anonfun$1(Main.scala:3)
	at scala.collection.immutable.List.map(List.scala:248)
	at Main$package$.run(Main.scala:3)
	at run.main(Main.scala:1)

@main def run(): Unit =
  val raw = List("10", "20", "3O")
  val (good, bad) = raw.partition(_.toIntOption.isDefined)
  println(good.map(_.toInt).sum)
  println(s"rejected: $bad")

def sumTo(n: Long): Long =
  if n == 0 then 0 else n + sumTo(n - 1)

@main def run(): Unit =
  println(sumTo(100_000))

Exception in thread "main" java.lang.StackOverflowError
	at Main$package$.sumTo(Main.scala:2)
	at Main$package$.sumTo(Main.scala:2)
	at Main$package$.sumTo(Main.scala:2)
	at Main$package$.sumTo(Main.scala:2)
	...

import scala.annotation.tailrec

def sumTo(n: Long): Long =
  @tailrec def loop(i: Long, acc: Long): Long =
    if i == 0 then acc else loop(i - 1, acc + i)
  loop(n, 0)

@main def run(): Unit =
  println(sumTo(100_000))

When the program runs but gives the wrong answer, you need to see its values. Start simple and escalate: a println, then the REPL to try a single expression, then a real debugger when you need to pause and look around.

println and tap: look inside a pipeline

Long chains of map and filter are hard to println without breaking them apart. scala.util.chaining adds tap, which runs a side effect on a value and passes the value on unchanged — you can drop it between any two steps and delete it afterwards.

import scala.util.chaining.*

@main def run(): Unit =
  val result = List(5, 3, 8, 1)
    .tap(xs => println(s"input:    $xs"))
    .filter(_ > 2)
    .tap(xs => println(s"filtered: $xs"))
    .map(_ * 10)
    .tap(xs => println(s"mapped:   $xs"))
    .sum
  println(result)

input:    List(5, 3, 8, 1)
filtered: List(5, 3, 8)
mapped:   List(50, 30, 80)
160

Logging instead of println

//> using dep ch.qos.logback:logback-classic:1.5.18
//> using dep com.typesafe.scala-logging::scala-logging:3.9.5
import com.typesafe.scalalogging.LazyLogging

object OrderService extends LazyLogging:
  def place(id: Int, qty: Int): Unit =
    logger.debug(s"placing order $id qty=$qty")   // only built if DEBUG is on
    if qty <= 0 then logger.warn(s"order $id rejected: qty=$qty")
    else logger.info(s"order $id placed")

In a service, use a logger (SLF4J with Logback, or scala-logging on top of it). Levels let you keep debug lines in the code and switch them on only when needed.

The REPL and scala-cli

$ scala
scala> "3O".toIntOption
val res0: Option[Int] = None

scala> List(1, 2, 3).sliding(2).toList
val res1: List[List[Int]] = List(List(1, 2), List(2, 3))

scala> :type List(1, "a")
List[Int | String]

scala> :quit

# a REPL with your project's file and libraries on the classpath
$ scala repl Main.scala

# rerun on every save while you debug
$ scala run --watch Main.scala

The REPL evaluates one expression at a time and shows its type — the fastest way to check what a method returns.

A real debugger: IntelliJ IDEA and Metals

1. 1
   Set a breakpoint

   Click in the gutter next to a line number in IntelliJ IDEA (with the Scala plugin) or VS Code (with the Metals extension).

2. 2
   Start in debug mode

   IntelliJ: the bug icon next to your @main or test. Metals: the debug code lens that appears above @main and each test.

3. 3
   Inspect

   When execution pauses, the Variables panel shows every local value, including the fields of case classes. Hover over any expression to see its value.

4. 4
   Step

   Step over runs the current line; step into enters the method it calls; step out finishes the current method. Conditional breakpoints (order.id == 2) stop only on the case you care about.

5. 5
   Evaluate

   The Evaluate Expression window runs Scala code against the paused program — try a fix before editing the file.

Let the compiler find bugs for you

//> using scala 3.9.0
//> using options -deprecation -feature -Wunused:all -Werror

scala-cli directives (sbt: scalacOptions ++= Seq(...)). -Wunused:all flags unused imports, locals and parameters — often a sign of a mistake. -Werror turns every warning, including non-exhaustive matches, into an error.

Bookmark this table. When you meet an error, find its first line here, then jump to the card for the cause and the fix.

Compile error

A problem the compiler proves before the program runs; nothing executes until it is fixed.

Runtime exception

An error thrown while the program runs, printed with a stack trace; depends on the data.

Stack trace

The chain of method calls in progress when an exception was thrown, newest call first.

Frame

One line of a stack trace: a method, its file and line number.

Caused by

A section of a stack trace showing an exception that was wrapped inside another; the last one is usually the root cause.

-explain

Compiler flag that prints a long explanation for each error.

Exhaustivity check

The compiler's check that a match on an enum or sealed trait handles every case.

MatchError

The runtime exception thrown when a value matches no case of a match expression.

tap

Method from scala.util.chaining that runs a side effect on a value and returns the value unchanged.

Breakpoint

A marked line where a debugger pauses the program so you can inspect its values.