← Back to DevBytes
Developer Tutorial July 08, 2026 13 min read

Error Handling Patterns in Nim

Introduction to Error Handling in Nim

Error handling is a fundamental discipline in software development, and Nim provides a uniquely flexible toolkit for managing failures. Rather than enforcing a single paradigm, Nim combines traditional exception-based error handling with functional-style return types, allowing developers to choose the most appropriate strategy for each situation. This hybrid approach draws from the best practices of both the Python and Rust ecosystems, giving Nim code both readability and robustness.

At its core, Nim error handling revolves around three pillars: exceptions (using try/except/finally/raise), optional types (via std/options), and discriminated union return types (often custom Result types). Understanding when and how to combine these mechanisms is what separates well-structured Nim applications from fragile ones.

Why Error Handling Matters in Nim

🚀 Deploy your AI agent in 10 minutes

Managed Hermes hosting. Zero DevOps. 100M tokens/mo included.

Try it free →

Nim compiles to C (or C++/Objective-C/JavaScript), which means it operates close to the metal. Unlike interpreted languages where a crash might simply propagate up to a REPL, unhandled errors in Nim can lead to silent memory corruption, resource leaks, or abrupt program termination with little diagnostic information. Proper error handling:

Core Error Handling Mechanisms

Exceptions: try/except/finally

Nim's exception model is inspired by Python but adds compile-time effect tracking. You raise an exception object (which can be any type, though conventionally ref object of CatchableError), catch it with try/except, and guarantee cleanup with finally.

import std/strformat

type
  DatabaseError = ref object of CatchableError
  ConnectionError = ref object of DatabaseError
  QueryError = ref object of DatabaseError

proc connect(dbUrl: string): void =
  if dbUrl == "":
    raise ConnectionError(msg: "Empty database URL")
  echo &"Connected to {dbUrl}"

proc executeQuery(query: string): string =
  if query == "":
    raise QueryError(msg: "Empty query string")
  # Simulated execution
  result = &"Results for: {query}"

proc runDatabaseOperation(dbUrl: string, query: string): string =
  try:
    connect(dbUrl)
    result = executeQuery(query)
  except ConnectionError as e:
    echo &"Connection failed: {e.msg}"
    result = "FALLBACK_DATA"
  except QueryError as e:
    echo &"Query failed: {e.msg}"
    raise  # Re-raise to let caller handle it
  finally:
    echo "Closing connection resources (always runs)"

# Usage
echo runDatabaseOperation("localhost:5432", "SELECT * FROM users")
echo runDatabaseOperation("", "SELECT * FROM users")  # Triggers ConnectionError

The finally block executes regardless of whether an exception occurred, making it ideal for resource cleanup. The except clause can match specific exception types in a type hierarchy, and using raise without arguments re-raises the current exception.

Option Type for Absence of Value

For cases where a value might legitimately be absent (rather than an error occurring), Nim's std/options module provides Option[T]. This is a safer, more explicit alternative to returning nil or sentinel values like empty strings.

import std/options

proc findUserById(id: int): Option[string] =
  let users = @["alice", "bob", "charlie"]
  if id >= 0 and id < users.len:
    result = some(users[id])
  else:
    result = none(string)

# Pattern 1: Checking with isSome/isNone
let user1 = findUserById(1)
if user1.isSome:
  echo "Found user: ", user1.get()
else:
  echo "User not found"

# Pattern 2: Using get with default value
let user5 = findUserById(5)
echo "User or fallback: ", user5.get("anonymous")

# Pattern 3: Using map/flatten for chaining
proc uppercase(s: string): string = s.toUpperAscii()

let maybeUpper = findUserById(0).map(uppercase)
echo "Uppercased: ", maybeUpper.get("N/A")

# Pattern 4: unsafeGet (use only when you're CERTAIN it's Some)
let user2 = findUserById(2)
assert user2.isSome
echo user2.unsafeGet()  # No runtime check

Using Option forces callers to explicitly handle the absence case, eliminating the class of bugs where nil references cause segfaults deep in unrelated code. The functional combinators like map, flatten, and flatMap enable clean pipelines without repetitive nil checks.

Result Types for Explicit Success/Failure

While Nim doesn't include a universal Result type in its standard library, the pattern of using discriminated unions (or third-party packages like questionable) to represent success or failure explicitly is idiomatic. This approach, popularized by Rust and Haskell, makes error states visible in the type signature.

type
  ParseResult[T] = object
    case success: bool
    of true:
      value: T
    of false:
      errorMsg: string

proc parseIntResult(s: string): ParseResult[int] =
  try:
    let n = parseInt(s)
    ParseResult[int](success: true, value: n)
  except ValueError:
    ParseResult[int](success: false, errorMsg: "Invalid integer: " & s)

proc sqrtResult(n: int): ParseResult[float] =
  if n < 0:
    ParseResult[float](success: false, errorMsg: "Cannot compute sqrt of negative number")
  else:
    ParseResult[float](success: true, value: sqrt(float(n)))

# Chaining result operations
proc processInput(s: string): ParseResult[float] =
  let parsed = parseIntResult(s)
  if not parsed.success:
    result = ParseResult[float](success: false, errorMsg: parsed.errorMsg)
    return
  let rooted = sqrtResult(parsed.value)
  if not rooted.success:
    result = ParseResult[float](success: false, errorMsg: rooted.errorMsg)
    return
  result = ParseResult[float](success: true, value: rooted.value)

# Using the chain
let r1 = processInput("25")
if r1.success:
  echo "Square root: ", r1.value
else:
  echo "Error: ", r1.errorMsg

let r2 = processInput("-5")
if r2.success:
  echo "Square root: ", r2.value
else:
  echo "Error: ", r2.errorMsg

This pattern shines in complex pipelines where each step can fail for different reasons. The compiler ensures you check success before accessing value, preventing accidental use of invalid data.

Defect vs Exception: The Two Flavors of Errors

Nim distinguishes between Defects (programming bugs that should not be caught) and Exceptions (recoverable runtime errors). A Defect (like IndexDefect, RangeDefect, or AssertionDefect) indicates a logic error in your code — catching it is considered bad practice. Exceptions (derived from CatchableError) represent external failures like network issues or invalid user input that can be handled gracefully.

import std/strformat

type
  MyAppError = ref object of CatchableError  # Recoverable
  # Defects are built-in: IndexDefect, RangeDefect, AssertionDefect, etc.

proc safeDivide(a, b: int): float =
  if b == 0:
    raise MyAppError(msg: "Division by zero")
  result = float(a) / float(b)

# This is a Defect - should NOT be caught in production
proc triggerIndexDefect(): void =
  let arr = @[1, 2, 3]
  echo arr[100]  # Raises IndexDefect

# Proper pattern: catch only CatchableError
try:
  echo safeDivide(10, 0)
except MyAppError as e:
  echo &"Recoverable error: {e.msg}"
# IndexDefect would NOT be caught here - it bubbles up as a defect

The raises Pragma: Compile-Time Effect Tracking

Nim's {.raises.} pragma lets you annotate which exceptions a procedure may raise. The compiler then verifies this at compile time, giving you Rust-like guarantees about error propagation.

type
  IOError = ref object of CatchableError
  ParseError = ref object of CatchableError

# Declare that this proc ONLY raises IOError
proc readConfig(path: string): string {.raises: [IOError].} =
  if path == "":
    raise IOError(msg: "Empty path")
  result = "config contents"

# This will NOT compile because it could raise ParseError
# but the raises pragma only lists IOError
proc brokenProc(): string {.raises: [IOError].} =
  try:
    result = readConfig("config.txt")
  except IOError:
    raise ParseError(msg: "Parse failed")  # Compile error!

# Correct version: list all possible raised types
proc fixedProc(): string {.raises: [IOError, ParseError].} =
  try:
    result = readConfig("config.txt")
  except IOError:
    raise ParseError(msg: "Parse failed")

Using {.raises: [].} (empty list) declares that a procedure raises no exceptions at all. The compiler will error if any exception could escape. This is invaluable for library authors who want to provide strong guarantees to consumers.

Practical Patterns and How to Use Them

Pattern 1: Catch, Enrich, and Re-raise

When an error occurs deep in your stack, catching it and adding context before re-raising dramatically improves debugging. This pattern preserves the original exception while wrapping it in domain-specific information.

import std/strformat

type
  ValidationError = ref object of CatchableError
  ProcessingError = ref object of CatchableError

proc validateEmail(email: string): void =
  if not email.contains('@'):
    raise ValidationError(msg: "Missing @ symbol")

proc processUser(id: int, email: string): void {.raises: [ProcessingError].} =
  try:
    validateEmail(email)
    # Simulate database work
    if id <= 0:
      raise ValueError(msg: "Invalid user ID")  # This will be wrapped
  except ValidationError as e:
    # Add context and re-raise as a different type
    let enriched = ProcessingError(
      msg: &"User {id} validation failed: {e.msg}"
    )
    raise enriched
  except ValueError as e:
    let enriched = ProcessingError(
      msg: &"User {id} processing error: {e.msg}"
    )
    raise enriched

try:
  processUser(42, "bad-email-no-at")
except ProcessingError as e:
  echo "Top-level handler caught: ", e.msg

Pattern 2: Option Chaining with Functional Combinators

When working with sequences of optional values, Nim's functional combinators eliminate boilerplate and make intent crystal clear.

import std/options, std/strutils

proc parsePositiveEven(s: string): Option[int] =
  let n = parseInt(s)
  if n.isSome and n.get() > 0 and n.get() mod 2 == 0:
    result = n
  else:
    result = none(int)

proc double(x: int): int = x * 2

proc formatResult(x: int): string = &"Result: {x}"

# Chain operations on Option values
let input = "42"

# Using map to transform the inner value
let doubled = parsePositiveEven(input).map(double)
echo doubled.get("invalid")

# Chaining multiple maps
let finalStr = parsePositiveEven(input)
  .map(double)
  .map(formatResult)
echo finalStr.get("invalid")

# Handling a list of inputs
let inputs = @["12", "abc", "16", "-5", "8"]
for s in inputs:
  let result = parsePositiveEven(s)
  if result.isSome:
    echo &"✓ {s} -> {result.get()}"
  else:
    echo &"✗ {s} skipped"

Pattern 3: Custom Result with Operation Chaining

For multi-step operations where each step can fail, you can build a fluent chain that short-circuits on the first error. This avoids deeply nested if blocks.

type
  FileResult[T] = object
    case ok: bool
    of true:
      value: T
    of false:
      error: string

proc readFile(path: string): FileResult[string] =
  if path.len == 0:
    FileResult[string](ok: false, error: "Empty path")
  elif not path.endsWith(".txt"):
    FileResult[string](ok: false, error: "Only .txt files supported")
  else:
    FileResult[string](ok: true, value: "File content of " & path)

proc parseContent(content: string): FileResult[int] =
  if content.len < 5:
    FileResult[int](ok: false, error: "Content too short")
  else:
    FileResult[int](ok: true, value: content.len)

proc validateLength(len: int, minLen: int): FileResult[int] =
  if len < minLen:
    FileResult[int](ok: false, error: &"Length {len} below minimum {minLen}")
  else:
    FileResult[int](ok: true, value: len)

# Flat chain using a helper template
template chain[T, U](r: FileResult[T], next: proc(x: T): FileResult[U]): FileResult[U] =
  if r.ok:
    next(r.value)
  else:
    FileResult[U](ok: false, error: r.error)

proc processFile(path: string): FileResult[int] =
  let step1 = readFile(path)
  if not step1.ok:
    return FileResult[int](ok: false, error: step1.error)
  let step2 = parseContent(step1.value)
  if not step2.ok:
    return FileResult[int](ok: false, error: step2.error)
  let step3 = validateLength(step2.value, 10)
  if not step3.ok:
    return FileResult[int](ok: false, error: step3.error)
  FileResult[int](ok: true, value: step3.value)

echo processFile("data.txt")
echo processFile("")  # Error case

Pattern 4: Combining Exceptions with Result Types

Sometimes you need to bridge code that uses exceptions with code that expects return-based errors. This pattern provides a clean adapter layer.

import std/strformat

type
  SafeResult[T] = object
    case success: bool
    of true:
      data: T
    of false:
      message: string

# Convert exception-throwing code to Result-returning code
template tryToResult[T](body: untyped): SafeResult[T] =
  try:
    SafeResult[T](success: true, data: body)
  except CatchableError as e:
    SafeResult[T](success: false, message: &"{e.name}: {e.msg}")

proc riskyParseInt(s: string): int =
  if s.len == 0:
    raise ValueError(msg: "Empty string")
  result = parseInt(s)

proc riskyFileRead(path: string): string =
  if path.len == 0:
    raise IOError(msg: "Path is empty")
  result = "Simulated content from " & path

# Wrap risky operations
let r1 = tryToResult[int](riskyParseInt("42"))
if r1.success:
  echo "Parsed: ", r1.data
else:
  echo "Parse error: ", r1.message

let r2 = tryToResult[int](riskyParseInt(""))
if r2.success:
  echo "Parsed: ", r2.data
else:
  echo "Parse error: ", r2.message

let r3 = tryToResult[string](riskyFileRead("config.txt"))
if r3.success:
  echo "File: ", r3.data
else:
  echo "File error: ", r3.message

Pattern 5: Defer for Deterministic Cleanup

Nim's defer statement provides RAII-style cleanup without needing finally blocks. It's particularly useful in functions with multiple exit points where resource management would otherwise be scattered.

import std/strformat

proc writeLogEntries(filename: string, entries: seq[string]): void =
  let f = open(filename, fmWrite)
  defer: f.close()  # Guaranteed to run when proc exits

  for entry in entries:
    if entry.len == 0:
      raise ValueError(msg: "Empty log entry not allowed")
    f.writeLine(entry)

  # Even if an exception is raised above, defer ensures f.close() runs

proc processWithCleanup(): void =
  echo "Starting process..."
  defer: echo "Cleanup: releasing locks"
  defer: echo "Cleanup: closing connections"

  # Defer statements run in LIFO order on scope exit
  echo "Doing work..."
  # If an exception occurs, defers still execute

processWithCleanup()

Best Practices

Match the Mechanism to the Failure Type

Always Document Raises Annotations

For any public API, specify {.raises.} pragmas. This transforms exception documentation from a comment into a compiler-enforced contract. Start with {.raises: [].} and expand the list only when necessary — it reveals accidental exception leakage at compile time.

# Bad: no raises annotation
proc processData(input: string): int =
  parseInt(input)  # Could raise ValueError

# Good: documented and compiler-checked
proc processData(input: string): int {.raises: [ValueError].} =
  parseInt(input)

# Best: handle internally where possible
proc processDataSafe(input: string): int {.raises: [].} =
  try:
    result = parseInt(input)
  except ValueError:
    result = 0  # Fallback, no exception escapes

Never Swallow Errors Silently

Catching an exception and doing nothing with it (a "bare except" or empty handler) creates debugging nightmares. If you catch an error, you must either handle it meaningfully, log it, enrich it, or re-raise it.

# Dangerous: silent swallow
try:
  criticalOperation()
except:
  discard  # Error vanishes - terrible practice

# Acceptable: logged and re-raised
try:
  criticalOperation()
except CatchableError as e:
  echo &"ERROR in criticalOperation: {e.msg}"
  raise  # Propagate

# Good: handled with fallback
try:
  let data = fetchFromNetwork()
except CatchableError:
  let data = fetchFromCache()  # Graceful degradation

Use finally or defer for Cleanup

Any operation that acquires a resource (file handle, socket, lock, memory allocation) must have a corresponding release in finally or defer. This ensures cleanup even when exceptions skip normal control flow.

import std/locks

var myLock: Lock
myLock.initLock()

proc lockedWork(): void =
  acquire(myLock)
  defer: release(myLock)  # Guaranteed release
  # Work that might raise exceptions
  doAssert 1 + 1 == 2
  echo "Critical section complete"

Create Domain-Specific Exception Hierarchies

Instead of raising generic CatchableError, build a typed exception tree that reflects your domain. This allows callers to catch specific error categories without parsing strings.

type
  AppError = ref object of CatchableError
  ConfigError = ref object of AppError
    configFile: string
  NetworkError = ref object of AppError
    endpoint: string
    retryCount: int
  AuthError = ref object of NetworkError
    username: string

proc authenticateUser(username: string, password: string): void =
  if password.len < 8:
    raise AuthError(
      username: username,
      msg: "Password too short"
    )

try:
  authenticateUser("alice", "123")
except AuthError as e:
  echo &"Auth failed for {e.username}: {e.msg}"
except NetworkError as e:
  echo &"Network issue at {e.endpoint}"
except AppError as e:
  echo &"General app error: {e.msg}"

Prefer Return-Based Errors in Library APIs

When building libraries consumed by other developers, return-based error handling (Option or Result) forces callers to confront failure cases. Exceptions can be ignored accidentally, but a Result type must be unpacked explicitly.

# Library API: forces caller to check
proc findConfiguration(key: string): Option[string] =
  let config = {"host": "localhost", "port": "5432"}.toTable
  if key in config:
    result = some(config[key])
  else:
    result = none(string)

# Caller must handle both cases
let host = findConfiguration("host")
if host.isSome:
  echo "Connecting to ", host.get()
else:
  echo "Host not configured, using default"

Test Error Paths Thoroughly

Happy-path tests are easy; error-path tests are what prevent production incidents. Write explicit unit tests for each exception variant, each Option none case, and each Result failure branch. Nim's std/unittest module makes this straightforward.

import std/unittest, std/options

proc safeDivide(a, b: float): Option[float] =
  if b == 0.0:
    result = none(float)
  else:
    result = some(a / b)

suite "safeDivide error paths":
  test "division by zero returns none":
    check safeDivide(10.0, 0.0).isNone

  test "valid division returns some":
    let r = safeDivide(10.0, 2.0)
    check r.isSome
    check r.get() == 5.0

  test "negative divisor works":
    let r = safeDivide(10.0, -2.0)
    check r.isSome
    check r.get() == -5.0

Conclusion

Nim's error handling ecosystem rewards deliberate choice. Exceptions provide the familiarity and convenience of stack-unwinding with finally guarantees; Option types eliminate null-reference bugs through type-system enforcement; and Result types bring Rust-style explicitness to failure propagation. The {.raises.} pragma ties everything together, turning runtime uncertainty into compile-time verification.

The most effective Nim developers treat error handling not as an afterthought but as a first-class design concern. By matching the mechanism to the failure category, documenting effect annotations, never swallowing errors silently, and testing failure paths as thoroughly as success paths, you build applications that are resilient, debuggable, and maintainable. Start with the patterns outlined here, adapt them to your domain, and let Nim's type system work for you rather than against you.

🚀 Need a reliable AI agent for your project?

Deploy Hermes Agent in 10 minutes. Managed hosting, zero DevOps.

Get Started — $23.99/mo
← Back to all articles