Mojo Custom Errors

Custom errors let you define specific, named error conditions that carry meaningful context about what went wrong. Instead of raising a generic Error("something failed"), you create domain-specific error types that communicate intent clearly — to other developers, to log systems, and to any code that needs to handle different failures differently.

Why Custom Errors Matter

Generic error:                     Custom error:
  raise Error("failed")              raise ValidationError("age", -5,
                                         "must be non-negative")

  Caller sees:                       Caller sees:
  "failed"                           field="age", value=-5,
  → What failed? Where? Why?         reason="must be non-negative"
  → Hard to handle programmatically  → Easy to log, display, retry

Building a Custom Error Type

Mojo does not yet have a built-in error hierarchy. The standard pattern is to create a struct that formats a descriptive message string, then raise a standard Error constructed from that message.

struct ValidationError:
    var field:  String
    var value:  String
    var reason: String

    fn __init__(inout self, field: String, value: String, reason: String):
        self.field  = field
        self.value  = value
        self.reason = reason

    fn to_error(self) -> Error:
        return Error(
            "ValidationError: field='" + self.field +
            "' value='" + self.value +
            "' reason='" + self.reason + "'"
        )

fn validate_age(age: Int) raises:
    if age < 0:
        raise ValidationError("age", String(age), "must be non-negative").to_error()
    if age > 150:
        raise ValidationError("age", String(age), "exceeds realistic maximum").to_error()

fn main():
    try:
        validate_age(-3)
    except e:
        print(str(e))
        # ValidationError: field='age' value='-3' reason='must be non-negative'

A Library of Domain Errors

Group related error types in one place so any module in your project can import and raise them consistently.

# File: errors.mojo

struct NotFoundError:
    var resource: String
    var id:       String

    fn __init__(inout self, resource: String, id: String):
        self.resource = resource
        self.id = id

    fn to_error(self) -> Error:
        return Error("NotFoundError: " + self.resource + " with id='" + self.id + "' not found")

struct PermissionError:
    var user:      String
    var operation: String

    fn __init__(inout self, user: String, operation: String):
        self.user = user
        self.operation = operation

    fn to_error(self) -> Error:
        return Error("PermissionError: user='" + self.user +
                     "' cannot perform '" + self.operation + "'")

struct RangeError:
    var param: String
    var value: Float64
    var lo:    Float64
    var hi:    Float64

    fn __init__(inout self, param: String, value: Float64, lo: Float64, hi: Float64):
        self.param = param
        self.value = value
        self.lo = lo
        self.hi = hi

    fn to_error(self) -> Error:
        return Error(
            "RangeError: " + self.param +
            "=" + String(self.value) +
            " not in [" + String(self.lo) + ", " + String(self.hi) + "]"
        )

Using the Error Library

fn get_user(user_id: String) raises -> String:
    if user_id == "":
        raise NotFoundError("User", user_id).to_error()
    if user_id == "admin":
        return "Alice (admin)"
    raise NotFoundError("User", user_id).to_error()

fn delete_user(user_id: String, caller: String) raises:
    if caller != "admin":
        raise PermissionError(caller, "delete_user").to_error()
    print("User", user_id, "deleted")

fn set_temperature(t: Float64) raises:
    if t < -273.15 or t > 10000.0:
        raise RangeError("temperature", t, -273.15, 10000.0).to_error()
    print("Temperature set to", t)

fn main():
    try:
        var user = get_user("unknown_id")
    except e:
        print(str(e))
        # NotFoundError: User with id='unknown_id' not found

    try:
        delete_user("user42", "guest")
    except e:
        print(str(e))
        # PermissionError: user='guest' cannot perform 'delete_user'

    try:
        set_temperature(-300.0)
    except e:
        print(str(e))
        # RangeError: temperature=-300.0 not in [-273.15, 10000.0]

Parsing Error Types from Messages

When a function can fail in multiple ways, the caller may need to distinguish error types. Embed a type tag in the message and check it in the except block.

fn classify_error(e: Error) -> String:
    var msg = str(e)
    if msg.startswith("ValidationError"):
        return "validation"
    elif msg.startswith("NotFoundError"):
        return "not_found"
    elif msg.startswith("PermissionError"):
        return "permission"
    else:
        return "unknown"

fn main():
    try:
        var user = get_user("")
    except e:
        var kind = classify_error(e)
        if kind == "not_found":
            print("Show 404 page")
        elif kind == "permission":
            print("Redirect to login")
        else:
            print("Show generic error:", str(e))

Error routing diagram:

  Function raises Error
         │
         ▼
  except e:
    classify_error(e)
         │
  ┌──────┼──────────┐
  ▼      ▼          ▼
 404  login      generic
 page redirect   handler

Error Context Builder

A context builder pattern adds location information — file, function, line — to any error message automatically.

fn with_context(e: Error, context: String) -> Error:
    return Error("[" + context + "] " + str(e))

fn load_config(path: String) raises -> String:
    try:
        if path == "":
            raise Error("path is empty")
        return "config data"
    except e:
        raise with_context(e, "load_config")

fn start_app() raises:
    try:
        var cfg = load_config("")
    except e:
        raise with_context(e, "start_app")

fn main():
    try:
        start_app()
    except e:
        print(str(e))
        # [start_app] [load_config] path is empty

Key Takeaways

Custom error types communicate the specific reason, location, and context of a failure rather than just "something failed." Build error structs with descriptive fields and a to_error() method that produces a formatted Error object. Group related error types in a dedicated module so every part of your project uses consistent error messages. Embed type tags at the start of error messages to enable programmatic classification in except blocks. Context builders wrap existing errors with location information as they propagate up the call stack, giving you a readable error trail without a stack trace.