Best exception to throw in pattern matching in Scala

by

Summary

A developer asked about the best exception to throw in a pattern matching expression for a function that swaps the first two elements of an integer array. The specific question focused on whether to use a generic Exception or a more specific type like MatchError. The core issue here is not just selecting an exception class, but understanding exception semantics in functional programming and Scala’s specific exception hierarchy. Using Exception is verbose and non-idiomatic, while using MatchError is semantically incorrect for a business logic failure (domain validation).

Root Cause

The root cause is a misunderstanding of the Liskov Substitution Principle applied to exceptions and the specific semantic meaning of Scala’s MatchError.

  1. Overly Broad Exception Type: Throwing a generic Exception (or RuntimeException) catches the entire spectrum of JVM errors, including system-level failures. This makes it impossible for calling code to distinguish between a “business rule violation” and a “system crash” without parsing the error message string—a brittle practice.
  2. Semantic Misuse of MatchError: MatchError in Scala is designed specifically for when a partial function (like a case statement) receives input that does not match any of its defined patterns. It signals a programmer error or a logical impossibility. In this specific scenario, an array with fewer than two elements is a valid, expected state that requires handling (validation), not an “unmatchable” pattern.

Why This Happens in Real Systems

Developers transitioning from languages like Python or Java often carry over habits that don’t translate well to Scala’s functional ecosystem.

  • Type vs. Meaning Confusion: In Python, throwing a generic Exception is common because exceptions are often used for control flow. In Scala, exceptions are expensive and should be reserved for truly exceptional, unrecoverable events, or adhered to via the Try/Either monads. Developers often focus on “does it compile?” rather than “is this the correct semantic signal?”
  • The “Partial Function” Trap: It is easy to treat pattern matching solely as a syntax for branching (if/else). However, pattern matching creates a Partial Function. When a developer writes a match without a catch-all case (case _), they implicitly rely on the compiler to handle non-matching cases. If they manually intervene (like throwing an exception) in a non-catch-all branch, they are likely solving the wrong problem—usually, the match itself is too restrictive.

Real-World Impact

  • API Pollution: Throwing a generic Exception clutters the stack trace with non-specific types. Monitoring tools (like Sentry or Datadog) group exceptions by type. A Exception wrapper prevents proper aggregation of error metrics.
  • Brittle Error Recovery: Calling code cannot safely recover. If a downstream service catches Exception, it might inadvertently swallow a critical OutOfMemoryError or InterruptedException alongside your business logic error.
  • Loss of Type Safety: Scala encourages encoding failure states in the type system (e.g., Either[Error, Array[Int]]). Throwing exceptions breaks the flow of pure functional code, forcing the caller to wrap the call in a Try block, which adds overhead and complexity.

Example or Code

Here is the corrected implementation. Instead of throwing an exception during pattern matching, we validate the input upfront or return a result type that accounts for failure (e.g., Option or Either).

The Scala Idiomatic Approach (Functional):

def swap2(arrayOfInts: Array[Int]): Option[Array[Int]] = {
  // We treat "less than two" as a valid state, not an exception.
  // Option is better than throwing here because it forces the caller 
  // to handle the "not found" case at compile time.
  arrayOfInts match {
    case Array(a, b, rest @ _*) => 
      Some(Array.concat(Array(b, a), rest.toArray))
    case _ => 
      None
  }
}

If You Must Throw (Imperative Style):

If the requirement is strictly to throw an exception for legacy API compatibility, you should throw a specific, descriptive exception.

def swap2(arrayOfInts: Array[Int]): Array[Int] = arrayOfInts match {
  case Array(a, b, rest @ _*) => Array.concat(Array(b, a), rest.toArray)
  // Throwing here is valid, but the exception type must be specific.
  // IllegalArgumentException signals that the argument provided was incorrect.
  case _ => 
    throw new IllegalArgumentException("Array needs at least two integers.")
}

How Senior Engineers Fix It

Senior engineers do not just change the exception class; they question the control flow.

  1. Avoid Throwing in Pure Functions: Senior engineers prefer Total Functions. Instead of throwing, they return an Option[T] (if the value might be absent) or an Either[E, T] (if the value might be absent and you need to explain why).
    • Fix: Return Option[Array[Int]]. The None case handles the short array scenario naturally.
  2. Use Domain-Specific Exceptions: If exceptions are unavoidable (e.g., for integration with Java libraries), they use custom case classes extending RuntimeException or specific standard exceptions like IllegalArgumentException or NoSuchElementException.
  3. Exhaustiveness Checking: They ensure the pattern match is exhaustive. The original code missed the empty array case. A senior engineer adds a case Array() => ... or a catch-all case _ =>.
  4. Pattern Matching on Length: For array manipulation, checking arrayOfInts.length is often more performant and readable than pattern matching on the array structure, specifically for this kind of validation logic.

Why Juniors Miss It

  • Focus on Syntax, Not Semantics: Juniors often treat the compiler as a syntax checker rather than a logic validator. If it compiles, it feels “correct,” even if the semantic meaning (using MatchError for validation) is wrong.
  • Lack of Exposure to Functional Idioms: Coming from Python or Java, throwing exceptions is the primary way to signal failure. Juniors may not yet be comfortable with Option, Either, or Try types and how they compose.
  • Misunderstanding Pattern Matching Categories: They may not realize that pattern matching is divided into Total (covers all inputs) and Partial (covers some inputs) functions. Treating a partial function as total (or vice versa) leads to these specific exception choices.