Error handling

What it is and why it exists

Error handling represents an operation that didn’t produce its promised result and carries the reason to code that can decide what happens next. Swift errors are ordinary values: any type conforming to Error can be thrown. Enums work especially well for a finite set of failure categories, while associated values carry the context needed for a recovery decision.

A throwing function writes throws in its signature. Its call site must use try, making the possible early control transfer visible during review. Passing the error from the current scope to its caller is error propagation .

Errors and optionals solve different problems. An optional says that a value might be absent but doesn’t explain why; an error fits when the caller needs to distinguish invalid input, unavailable resources, insufficient permission, or another cause. Assertions and preconditions report programmer contract violations or broken invariants, so they aren’t substitutes for recoverable errors.

You meet error handling in parsing, filesystems, networking, persistence, and asynchronous APIs. The central design question isn’t “where can I add catch?” but which boundary knows enough to retry, fall back, inform the user, or translate the failure into a domain error.

How it works

An error path has four actions: define an error value, issue the failure with throw, mark the possible control transfer with try at the call site, and either handle or propagate it. throw immediately leaves the current normal path, so later statements on that path don’t run. A throwing function can return a value, but one invocation either returns or throws; it doesn’t do both.

A typical error enum puts stable categories in cases and dynamic information in associated values. For example, invalidCoupon(code:) supports programmatic handling better than a string error because callers can exhaustively match the category while retaining the exact coupon for a safe user message.

Swift provides four call forms:

1. try preserves the error so the current scope can catch or propagate it.
2. try? turns the success value into an optional and produces nil when the call throws.
3. try! asserts that the call won’t throw; a false assertion causes a runtime error.
4. Result<Success, Failure> stores either success or failure as a value, which fits caches, queues, or interfaces that still use completion callbacks.

Choose a representation by semantics

One failure shouldn’t be represented simultaneously as an optional, an error, and a Boolean flag. Choose one primary representation so callers can see what they must handle from the type and call syntax; convert once, explicitly, only when crossing a storage or callback boundary.

The table describes an API contract, not error severity. The same “record not found” condition can be nil in a search interface and an error in an update-by-primary-key interface; the caller’s promise and recovery needs decide.

A do–catch selects the first matching catch in source order. A pattern can match a particular error case, bind associated values, add a where condition, or use a patternless catch for everything left. Plain throws is equivalent to throws(any Error), so it usually needs a final fallback branch.

Swift 6 typed throws writes a concrete failure type as throws(MyError). The compiler rejects other thrown types in that function and can preserve the type through a call chain. A specific error type becomes part of the API contract, while unqualified throws allows an implementation and its dependencies to add error types later.

The handling site defines an abstraction boundary. A low-level function should expose enough information to diagnose failure, while a higher boundary can recover or translate implementation details into a domain error. Translation can retain the low-level cause in an associated value, a form of error wrapping ; don’t reduce it to a context-free generic string.

Catch where recovery is possible

Catching isn’t the same as handling. Printing an error and returning a normal value usually makes failure disappear from the type system; if this layer can’t take a different action, propagate it so a higher layer can decide.

A valid recovery action changes the outcome: retry an operation classified as transient, use an explicit fallback, ask the user to correct input, or translate a technical error into a stable domain failure. Logging alone doesn’t change the failed state, so it normally still needs a rethrow.

An error can pass through several intermediate functions that don’t catch it. That isn’t less robust; it avoids copying the same do–catch through every layer. Fewer boundaries make translation rules and observability policy easier to keep consistent.

Throwing initializers follow the same model: when input fails a condition before initialization completes, throw instead of producing a partly valid instance. The caller still uses try and receives no instance on failure.

Examples

Define, throw, and catch domain errors

The first example uses an enum to distinguish an empty cart from an invalid coupon. checkoutTotal uses plain throws, so its caller keeps a fallback catch for any Error value the signature permits.

Each loop iteration either prints a total or transfers control into one matching handler. The empty-cart branch doesn’t need the error value, while the coupon branch binds its associated value. The final catch isn’t decoration; it corresponds to the open error set exposed by plain throws.

Production business code usually doesn’t print at the low level. A UI boundary can turn emptyCart into an action message and attach invalidCoupon to an input field; a service can instead keep throwing and leave the decision to a caller that understands the user action.

Close the failure set with typed throws

Typed throws lets parseQuantity throw only QuantityError. Inside the patternless catch, error keeps the concrete enum type, so its switch must cover every case; adding a case later makes the compiler identify handling code that needs an update.

// # not executed here: Swift toolchain is not installed.
enum QuantityError: Error {
    case empty
    case notANumber(String)
    case outsideRange(Int)
}

func parseQuantity(_ text: String) throws(QuantityError) -> Int {
    guard !text.isEmpty else { throw .empty }
    guard let value = Int(text) else { throw .notANumber(text) }
    guard 1...20 ~= value else { throw .outsideRange(value) }
    return value
}

for input in ["3", "", "many", "25"] {
    do {
        print("quantity: \(try parseQuantity(input))")
    } catch {
        switch error {
        case .empty:
            print("quantity is empty")
        case .notANumber(let text):
            print("not a number: \(text)")
        case .outsideRange(let value):
            print("outside range: \(value)")
        }
    }
}

Not executed here: Swift toolchain is not installed.

The short form throw .empty works because the function signature already supplies the error type. A concrete type fits a function whose complete failure set is controlled by the current module; if the function directly propagates errors from several dependencies, forcing them into one enum can create wrapping code with no recovery value.

You can also write do throws(QuantityError) { ... } to constrain a do block explicitly. Swift can usually infer a single concrete error type, but spelling it out in a public function signature makes the contract immediately visible to callers.

Store failure in Result

The result type , Result, is an enum with .success and .failure cases. This function stores one inventory reservation as a value, so a caller can switch over it later instead of handling it immediately on the stack where it was produced.

// # not executed here: Swift toolchain is not installed.
enum StockError: Error {
    case invalidRequest
    case insufficient(available: Int)
}

func reserve(stock: Int, requested: Int) throws(StockError) -> Int {
    guard requested > 0 else { throw .invalidRequest }
    guard requested <= stock else { throw .insufficient(available: stock) }
    return stock - requested
}

func reservation(stock: Int, requested: Int) -> Result<Int, StockError> {
    do {
        return .success(try reserve(stock: stock, requested: requested))
    } catch {
        return .failure(error)
    }
}

for requested in [2, 7] {
    switch reservation(stock: 5, requested: requested) {
    case .success(let remaining):
        print("remaining: \(remaining)")
    case .failure(.invalidRequest):
        print("invalid request")
    case .failure(.insufficient(let available)):
        print("only \(available) available")
    }
}

Not executed here: Swift toolchain is not installed.

Result.get() rethrows a stored failure, map transforms only the success value, and mapError transforms only the failure. These operations compose in value pipelines, but they don’t decide which failures are recoverable and don’t replace a native async throws signature.

New asynchronous Swift APIs normally return a value directly and use async throws. An explicit Result adds value only when an outcome must be stored, passed as a collection element, or adapted to a callback protocol.

Preserve caller capabilities with rethrows

rethrows means a function can throw only when one of its function parameters throws; it can’t originate a new error. The call to audited with a nonthrowing closure needs no try, while a throwing closure propagates its error through the wrapper. defer runs before the current scope exits by either returning or throwing.

// # not executed here: Swift toolchain is not installed.
enum ExportError: Error {
    case empty
}

func audited<T>(_ operation: () throws -> T) rethrows -> T {
    print("begin")
    defer { print("end") }
    return try operation()
}

func export(rowCount: Int) throws(ExportError) -> String {
    guard rowCount > 0 else { throw .empty }
    return "report.csv"
}

let cached = audited { "cached.csv" }
print(cached)

do {
    print(try audited { try export(rowCount: 0) })
} catch ExportError.empty {
    print("empty export")
} catch {
    print("unexpected error: \(error)")
}

Not executed here: Swift toolchain is not installed.

defer fits releasing locks, closing manually managed handles, or restoring temporary state, but it doesn’t roll back business side effects that already committed. If the wrapper itself can throw because an audit write fails, it can’t be rethrows; it must use plain or typed throws to expose the larger failure set.

Pitfalls

Fix: use try? only when the reason is irrelevant and nil has an unambiguous meaning. At a data boundary, use do–catch to record approved diagnostics and then propagate or translate the error; don’t log complete input or sensitive associated values by default.

Fix: use ordinary try and handle or propagate the error. Consider try! only when failure truly means an unrecoverable programmer defect and tests plus encapsulation enforce the invariant; even then, keep the assertion at the smallest boundary.

Fix: put specific patterns first and keep a fallback for an open error set. When the failure set is genuinely closed, use typed throws and an exhaustive switch so a new case becomes a compile-time failure.

Fix: translate only at an abstraction boundary and retain the category and context needed for recovery. Store an underlying error as an associated value when diagnostics need it, while letting a separate logging policy decide which data may be emitted.

Fix: validate before irreversible side effects, use storage APIs with atomic guarantees, or design compensation for a multistep operation. Inject failure at every throwing step and inspect final state instead of merely asserting that some error arrived.

Further reading

• The Swift Programming Language: Error Handling
• The Swift Programming Language: Throwing Functions and Methods
• Swift Evolution SE-0413: Typed throws
• Apple Developer Documentation: Result