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

Error Handling Patterns in F#

Understanding Error Handling in F#

Error handling in F# represents a fundamental shift from the exception-based models common in languages like C# or Java. Instead of relying primarily on try/catch blocks and throwing exceptions, F# embraces a type-driven, functional approach where errors are treated as first-class values that can be composed, transformed, and propagated through your program's normal control flow. This philosophy is deeply rooted in the language's functional DNA and its strong type system.

What Is Functional Error Handling?

At its core, functional error handling means representing the possibility of failure directly in the type signature of a function. Rather than a function returning a value or throwing an exception, it returns a type that explicitly encodes both success and failure states. F# provides two primary types for this purpose:

These types allow you to chain operations together, handle errors at the appropriate level, and never accidentally ignore a failure case because the compiler ensures you handle both paths. 

// Option type - value may be present or absent
type Option<'T> =
    | Some of 'T
    | None

// Result type - operation may succeed or fail with an error
type Result<'T, 'Error> =
    | Ok of 'T
    | Error of 'Error

Why Error Handling Patterns Matter in F#

Traditional exception-based error handling introduces several problems that functional patterns elegantly solve:

By encoding errors in the type system, F# makes error handling:

The Core Error Handling Types

🚀 Deploy your AI agent in 10 minutes

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

Try it free →

Option Type: Handling Absence

The Option type is the simplest error handling pattern. Use it when the only failure mode is the absence of a value—there's no additional error information to convey. Common scenarios include looking up an item in a collection, finding a record in a database, or parsing a value that might not be present. 

// Function returning an Option
let tryFindEven (numbers: int list) : Option =
    numbers |> List.tryFind (fun n -> n % 2 = 0)

// Pattern matching on Option
let describeResult =
    match tryFindEven [1; 3; 5; 7; 9] with
    | Some n -> sprintf "Found even number: %d" n
    | None -> "No even number found"

// Using Option helpers
let result =
    tryFindEven [1; 2; 3; 4; 5]
    |> Option.map (fun n -> n * 10)
    |> Option.defaultValue 0
// result = 20

The key functions for working with Option include: 

// Chaining Option operations with bind
let tryParseInt (s: string) : Option =
    match System.Int32.TryParse(s) with
    | (true, n) -> Some n
    | (false, _) -> None

let tryDivideBy (divisor: int) (n: int) : Option =
    if divisor = 0 then None else Some (n / divisor)

let computeResult (input: string) (divisor: string) =
    tryParseInt input
    |> Option.bind (fun n ->
        tryParseInt divisor
        |> Option.bind (fun d ->
            tryDivideBy d n
        )
    )
    |> Option.map (fun result -> sprintf "Result: %d" result)
    |> Option.defaultValue "Could not compute"

// Usage
computeResult "100" "5"   // "Result: 20"
computeResult "100" "0"   // "Could not compute"
computeResult "abc" "5"   // "Could not compute"

Result Type: Handling Errors with Information

The Result type extends the Option pattern by allowing you to attach meaningful error information to the failure case. Use Result when you need to distinguish between different kinds of failures or when the caller needs details about what went wrong. This is the workhorse of F# error handling and the recommended default choice for most business logic. 

// Defining a domain-specific error type
type ValidationError =
    | InvalidEmail of string
    | InvalidAge of int
    | MissingRequiredField of string

// Function returning a Result
let validateEmail (email: string) : Result =
    if email.Contains("@") && email.Contains(".") then
        Ok email
    else
        Error (InvalidEmail email)

let validateAge (age: int) : Result =
    if age >= 0 && age <= 150 then
        Ok age
    else
        Error (InvalidAge age)

// Pattern matching on Result
let handleValidation =
    match validateEmail "not-an-email" with
    | Ok validEmail -> sprintf "Email '%s' is valid" validEmail
    | Error (InvalidEmail raw) -> sprintf "'%s' is not a valid email" raw
    | Error other -> sprintf "Other error: %A" other

Result Helpers and Composition

Like Option, Result supports map and bind, but with an important distinction: Result.map transforms only the success value, while Result.mapError transforms only the error value. The bind operation (Result.bind) allows chaining operations that each return a Result. 

// Result.map and Result.bind
let validateAndTransform (input: string) : Result =
    validateEmail input
    |> Result.map (fun email -> email.ToLower().Trim())

let processUser (email: string) (age: int) : Result =
    validateEmail email
    |> Result.bind (fun validEmail ->
        validateAge age
        |> Result.map (fun validAge ->
            sprintf "User with email %s and age %d is valid" validEmail validAge
        )
    )

// Usage
processUser "user@example.com" 25
// Ok "User with email user@example.com and age 25 is valid"

processUser "invalid" 25
// Error (InvalidEmail "invalid")

processUser "user@example.com" -5
// Error (InvalidAge -5)

Advanced Composition Patterns

Applicative Style: Combining Multiple Results

Sometimes you need to validate multiple independent values and collect all errors rather than failing on the first one. This is where applicative-style composition shines. Instead of using bind (which short-circuits on the first error), you can use a computation expression or a helper function to accumulate errors. 

// Custom Result builder for applicative-style error accumulation
type ResultBuilder() =
    member _.Bind(result, func) =
        match result with
        | Ok value -> func value
        | Error e -> Error e
    
    member _.Return(value) = Ok value

let result = ResultBuilder()

// Using the builder (short-circuiting, like bind)
let validateUserShortCircuit (email: string) (age: int) (name: string) =
    result {
        let! validEmail = validateEmail email
        let! validAge = validateAge age
        let validName =
            if System.String.IsNullOrWhiteSpace(name) then
                Error (MissingRequiredField "name")
            else
                Ok name
        let! finalName = validName
        return sprintf "User: %s, %s, %d" finalName validEmail validAge
    }

For scenarios where you want to collect all errors (not short-circuit), you can build a validation applicative that accumulates errors into a list: 

// Accumulating multiple errors using a list-based approach
type ValidationResult<'T> = Result<'T, ValidationError list>

let validateEmailCollecting (email: string) : ValidationResult =
    if email.Contains("@") && email.Contains(".") then
        Ok email
    else
        Error [InvalidEmail email]

let validateAgeCollecting (age: int) : ValidationResult =
    if age >= 0 && age <= 150 then
        Ok age
    else
        Error [InvalidAge age]

let validateNameCollecting (name: string) : ValidationResult =
    if System.String.IsNullOrWhiteSpace(name) then
        Error [MissingRequiredField "name"]
    else
        Ok name

// Collect all validation errors
let validateAll (email: string) (age: int) (name: string) : ValidationResult =
    match validateEmailCollecting email, validateAgeCollecting age, validateNameCollecting name with
    | Ok e, Ok a, Ok n ->
        Ok (sprintf "User: %s, %s, %d" n e a)
    | errors ->
        let allErrors =
            [ match (fun (x: ValidationResult<_>) -> x) with
              | Error e -> yield! e
              | Ok _ -> () ]
        // More explicitly:
        let gatheredErrors =
            [ if match validateEmailCollecting email with Error e -> true | _ -> false then
                  match validateEmailCollecting email with Error e -> yield! e | _ -> () 
              if match validateAgeCollecting age with Error e -> true | _ -> false then
                  match validateAgeCollecting age with Error e -> yield! e | _ -> ()
              if match validateNameCollecting name with Error e -> true | _ -> false then
                  match validateNameCollecting name with Error e -> yield! e | _ -> () ]
        Error gatheredErrors

// A cleaner helper for error accumulation
let collectErrors results =
    let errors = 
        results 
        |> List.choose (function Error e -> Some e | Ok _ -> None)
        |> List.collect id
    if List.isEmpty errors then Ok () else Error errors

// Even cleaner: using a fold
let validateAllFormFields (email: string) (age: int) (name: string) =
    let results = [
        validateEmailCollecting email |> Result.mapError List.singleton
        validateAgeCollecting age |> Result.mapError List.singleton
        validateNameCollecting name |> Result.mapError List.singleton
    ]
    let errors = results |> List.choose (function Error e -> Some e | _ -> None) |> List.concat
    if List.isEmpty errors then
        Ok (email, age, name)
    else
        Error errors

The Result Computation Expression

F# computation expressions provide a clean, imperative-looking syntax for composing Result-returning operations. F# 6 and later include a built-in task CE, but for Result you can either use a custom builder or leverage libraries like FsToolkit.ErrorHandling which provide robust CEs for Result, AsyncResult, and more. 

// A simple custom Result computation expression
type ResultBuilder() =
    member _.Bind(x, f) = 
        match x with
        | Ok v -> f v
        | Error e -> Error e
    member _.Return(x) = Ok x
    member _.ReturnFrom(x: Result<_, _>) = x
    member _.Zero() = Ok ()

let result = ResultBuilder()

// Using the computation expression
let processOrder (orderId: string) (quantity: int) =
    result {
        let! validatedId = 
            if System.String.IsNullOrWhiteSpace(orderId) then
                Error "Order ID cannot be empty"
            else
                Ok orderId
        
        let! validatedQuantity =
            if quantity <= 0 then
                Error "Quantity must be positive"
            elif quantity > 1000 then
                Error "Quantity exceeds maximum"
            else
                Ok quantity
        
        let totalPrice = validatedQuantity * 25 // some price calculation
        
        return (validatedId, validatedQuantity, totalPrice)
    }

// Usage
processOrder "ORD-123" 5
// Ok ("ORD-123", 5, 125)

processOrder "" 5
// Error "Order ID cannot be empty"

processOrder "ORD-123" 0
// Error "Quantity must be positive"

Async and Result Combined

In real-world applications, operations often need to be both asynchronous and fallible. The combination of Async and Result creates an Async<Result<'T, 'Error>> pattern, which can become unwieldy with nested pattern matching. A dedicated AsyncResult computation expression or helper functions dramatically simplify this. 

// AsyncResult helper module
module AsyncResult =
    let bind (f: 'T -> Async>) (x: Async>) : Async> =
        async {
            match! x with
            | Ok value -> return! f value
            | Error e -> return Error e
        }
    
    let map (f: 'T -> 'U) (x: Async>) : Async> =
        async {
            match! x with
            | Ok value -> return Ok (f value)
            | Error e -> return Error e
        }
    
    let retn (value: 'T) : Async> =
        async { return Ok value }
    
    let returnError (error: 'Error) : Async> =
        async { return Error error }

// Simulated async operations
let fetchUserFromDb (userId: int) : Async> =
    async {
        // Simulate async database call
        do! Async.Sleep 100
        if userId > 0 then
            return Ok $"User_{userId}"
        else
            return Error "Invalid user ID"
    }

let fetchOrdersForUser (username: string) : Async> =
    async {
        do! Async.Sleep 50
        if username.StartsWith("User_") then
            return Ok [1; 2; 3; 4; 5]
        else
            return Error "User not found in order system"
    }

// Composing async results
let getUserOrders (userId: int) =
    async {
        match! fetchUserFromDb userId with
        | Ok user ->
            match! fetchOrdersForUser user with
            | Ok orders -> return Ok (user, orders)
            | Error e -> return Error e
        | Error e -> return Error e
    }

// Using AsyncResult.bind for cleaner composition
let getUserOrdersClean (userId: int) =
    fetchUserFromDb userId
    |> AsyncResult.bind (fun user ->
        fetchOrdersForUser user
        |> AsyncResult.map (fun orders -> (user, orders))
    )

// Usage
getUserOrdersClean 42 |> Async.RunSynchronously
// Ok ("User_42", [1; 2; 3; 4; 5])

Interoperating with Exceptions

F# lives in the .NET ecosystem, so you'll inevitably encounter exceptions from libraries, I/O operations, or legacy code. The key is to catch exceptions at the boundaries and convert them into Result or Option types, keeping the rest of your code functional and pure. 

// Converting exception-throwing code to Result
let tryReadFile (path: string) : Result =
    try
        Ok (System.IO.File.ReadAllText(path))
    with
    | :? System.IO.FileNotFoundException ->
        Error $"File not found: {path}"
    | :? System.IO.IOException as ex ->
        Error $"IO error: {ex.Message}"
    | ex ->
        Error $"Unexpected error: {ex.Message}"

// Converting exception-throwing code to Option (when error details don't matter)
let tryParseDecimal (input: string) : Option =
    try
        Some (decimal input)
    with
    | :? System.FormatException
    | :? System.OverflowException ->
        None

// Async version with timeout handling
let fetchWebContent (url: string) : Async> =
    async {
        try
            let! content = Async.AwaitTask (httpClient.GetStringAsync(url)) // hypothetical
            return Ok content
        with
        | :? System.TimeoutException ->
            return Error "Request timed out"
        | :? System.Net.Http.HttpRequestException as ex ->
            return Error $"HTTP error: {ex.Message}"
        | ex ->
            return Error $"Unexpected: {ex.Message}"
    }

// Higher-order function to wrap any function in a Result
let wrapWithResult (f: unit -> 'T) : Result<'T, string> =
    try
        Ok (f())
    with ex ->
        Error ex.Message

// Usage
let result = wrapWithResult (fun () -> System.IO.File.ReadAllText "config.json")

The Error-Chaining Railway Pattern

A powerful mental model for Result-based error handling is the "Railway Oriented Programming" pattern. Think of your functions as railway tracks: successful results continue down the main track, while errors are shunted onto a parallel error track and bypass all subsequent transformations until you explicitly handle them. 

// Railway-oriented programming with Result
// Each function takes and returns Result, allowing seamless chaining

let validateOrder (order: {| Id: string; Qty: int |}) =
    if System.String.IsNullOrWhiteSpace(order.Id) then
        Error "Invalid order ID"
    elif order.Qty <= 0 then
        Error "Invalid quantity"
    else
        Ok order

let calculatePrice (order: {| Id: string; Qty: int |}) =
    Ok (order.Qty * 42.0) // price per unit

let applyDiscount (price: float) =
    if price > 1000.0 then
        Ok (price * 0.9) // 10% discount
    else
        Ok price

let formatReceipt (finalPrice: float) =
    Ok $"Receipt: Total = ${finalPrice:N2}"

// Chaining the railway
let processOrderPipeline (order: {| Id: string; Qty: int |}) =
    validateOrder order
    |> Result.bind calculatePrice
    |> Result.bind applyDiscount
    |> Result.bind formatReceipt

// Usage
processOrderPipeline {| Id = "ORD-1"; Qty = 10 |}
// Ok "Receipt: Total = $420.00"

processOrderPipeline {| Id = ""; Qty = 5 |}
// Error "Invalid order ID"

Best Practices for F# Error Handling

1. Choose the Right Type for the Job

Select your error representation based on the semantics of the failure: 

// Discriminated union for rich error information
type PaymentError =
    | InsufficientFunds of available: decimal * required: decimal
    | AccountFrozen of accountId: string
    | InvalidPaymentDetails of details: string
    | GatewayTimeout of attemptCount: int

type ProcessPayment = {
    AccountId: string
    Amount: decimal
    Currency: string
}

let processPayment (payment: ProcessPayment) : Result =
    // Rich error handling logic
    if payment.Amount <= 0m then
        Error (InvalidPaymentDetails "Amount must be positive")
    elif payment.Amount > 10000m then
        Error (InsufficientFunds (5000m, payment.Amount))
    else
        Ok $"Payment of {payment.Amount} processed"

2. Push Error Handling to the Boundaries

Keep your core business logic pure and functional. Catch exceptions at the edges of your system—in controllers, API handlers, database access layers, and file I/O—and convert them to Result types immediately. The inner domain logic should operate entirely on Options and Results. 

// Boundary: exception handling at the edge
let readConfiguration () : Result =
    try
        let json = System.IO.File.ReadAllText "appsettings.json"
        // parse and return configuration
        Ok (parseConfiguration json)
    with ex ->
        Error $"Failed to read configuration: {ex.Message}"

// Core: pure domain logic with no exceptions
let processConfiguration (config: Configuration) : Result =
    validatePort config.Port
    |> Result.bind (fun port ->
        validateHost config.Host
        |> Result.map (fun host -> { Port = port; Host = host })
    )

3. Use Computation Expressions for Readability

When you have a sequence of dependent operations (each feeding into the next), computation expressions provide a clean, readable syntax that looks almost imperative while remaining fully functional and safe. 

// Without CE - nested binds
let complexOperation input =
    validateInput input
    |> Result.bind (fun validated ->
        fetchData validated
        |> Result.bind (fun data ->
            transformData data
            |> Result.bind (fun transformed ->
                saveData transformed
                |> Result.map (fun saved -> (validated, saved))
            )
        )
    )

// With CE - much cleaner
let complexOperationCE input =
    result {
        let! validated = validateInput input
        let! data = fetchData validated
        let! transformed = transformData data
        let! saved = saveData transformed
        return (validated, saved)
    }

4. Avoid Throwing Exceptions in Core Logic

Reserve exceptions for truly exceptional circumstances—things like stack overflow, out of memory, or other unrecoverable situations. For expected failure modes (validation errors, not found, conflict, etc.), always use Result or Option. 

// Bad: throwing exceptions for expected failures
let findUser_Bad (id: int) =
    if id <= 0 then
        failwith "Invalid ID" // Don't do this
    // ... database lookup

// Good: using Result for expected failures
let findUser_Good (id: int) : Result =
    if id <= 0 then
        Error "User ID must be positive"
    else
        // database lookup
        match db.TryFind id with
        | Some user -> Ok user
        | None -> Error $"User {id} not found"

5. Provide Rich Error Context

When errors occur, the caller needs enough information to either recover, log meaningfully, or present a helpful message to the user. Design your error types thoughtfully. 

// Rich error type with context
type OrderError =
    | ValidationError of field: string * reason: string * attemptedValue: string
    | InventoryError of productId: string * requested: int * available: int
    | PaymentError of amount: decimal * failureReason: string * transactionId: string option
    
    // Human-readable error message
    member this.Message =
        match this with
        | ValidationError (field, reason, value) ->
            sprintf "Validation failed for '%s': %s (value: '%s')" field reason value
        | InventoryError (pid, req, avail) ->
            sprintf "Insufficient inventory for '%s': requested %d, available %d" pid req avail
        | PaymentError (amount, reason, txId) ->
            match txId with
            | Some id -> sprintf "Payment of %M failed (%s). Transaction: %s" amount reason id
            | None -> sprintf "Payment of %M failed: %s" amount reason

6. Leverage the Built-in Option and Result Modules

F# provides extensive built-in functions for Option and Result in the standard library modules Option and Result. Familiarize yourself with these to avoid reinventing the wheel: 

// Built-in Option functions
let transformed = Some 42 |> Option.map (fun x -> x * 2)        // Some 84
let filtered = Some 42 |> Option.filter (fun x -> x > 100)      // None
let orElse = None |> Option.orElse (Some 10)                     // Some 10
let orElseWith = None |> Option.orElseWith (fun () -> Some 99)   // Some 99
let contains = Some 42 |> Option.contains 42                     // true
let toList = Some 42 |> Option.toList                            // [42]
let toResult = None |> Option.toResult "Missing"                 // Error "Missing"

// Built-in Result functions (F# 4.1+)
let doubled = Ok 21 |> Result.map (fun x -> x * 2)               // Ok 42
let chained = Ok 21 |> Result.bind (fun x -> Ok (x * 2))        // Ok 42
let mappedError = Error "boom" |> Result.mapError (fun e -> e.Length) // Error 4
let defaultValue = Error "err" |> Result.defaultValue 42         // 42
let defaultWith = Error "err" |> Result.defaultWith (fun e -> e.Length) // 4
let isOk = Ok 42 |> Result.isOk                                  // true

7. Test Error Paths Explicitly

One of the greatest benefits of functional error handling is testability. Write unit tests for both success and failure paths as regular assertions—no need for exception-catching test infrastructure. 

// Testing error paths is straightforward
let testValidateEmail =
    // Success case
    assert (validateEmail "user@example.com" = Ok "user@example.com")
    
    // Failure cases
    assert (validateEmail "not-an-email" = Error (InvalidEmail "not-an-email"))
    assert (validateEmail "" = Error (InvalidEmail ""))
    
    // You can pattern match in tests too
    match validateEmail "test@test.com" with
    | Ok email -> printfn "Test passed: got %s" email
    | Error _ -> failwith "Expected Ok but got Error"

Common Error Handling Patterns in Practice

Pattern: Validation Pipeline

A common pattern is building a validation pipeline that collects all errors before returning. This is especially useful in web forms or API request validation. 

type UserInput = {
    Name: string
    Email: string
    Age: string // raw string input
}

type ValidationErrors = 
    | NameTooShort of minLength: int
    | InvalidEmailFormat of email: string
    | AgeNotANumber of rawValue: string
    | AgeOutOfRange of age: int

let validateName (name: string) =
    if name.Length < 2 then Error [NameTooShort 2]
    else Ok name

let validateEmailField (email: string) =
    if email.Contains("@") then Ok email
    else Error [InvalidEmailFormat email]

let validateAgeField (ageStr: string) =
    match System.Int32.TryParse(ageStr) with
    | (true, age) when age >= 0 && age <= 150 -> Ok age
    | (true, age) -> Error [AgeOutOfRange age]
    | (false, _) -> Error [AgeNotANumber ageStr]

let validateUserInput (input: UserInput) =
    let results = [
        validateName input.Name |> Result.mapError id
        validateEmailField input.Email |> Result.mapError id
        validateAgeField input.Age |> Result.mapError id
    ]
    let errors = results |> List.choose (function Error e -> Some e | _ -> None) |> List.collect id
    if List.isEmpty errors then
        Ok {| Name = input.Name; Email = input.Email; Age = input.Age |> int |}
    else
        Error errors

Pattern: Try/Recover

Sometimes you want to attempt an operation and, if it fails, try an alternative. This pattern composes elegantly with Result. 

let tryPrimarySource (key: string) : Result =
    if key = "cache" then Ok "data-from-cache"
    else Error "Not in cache"

let tryFallbackSource (key: string) : Result =
    if key = "db" then Ok "data-from-db"
    else Error "Not in database"

let tryAnotherFallback (key: string) : Result =
    Ok "default-data"

// Chain fallbacks
let getData (key: string) =
    tryPrimarySource key
    |> Result.orElseWith (fun _ -> tryFallbackSource key)
    |> Result.orElseWith (fun _ -> tryAnotherFallback key)

// Usage
getData "cache"  // Ok "data-from-cache"
getData "db"     // Ok "data-from-db"
getData "xyz"    // Ok "default-data"

Pattern: Tee/Logging Side Effects

You can inject logging or other side effects into a Result pipeline without breaking the flow using a "tee" function that passes the value through while performing a side effect. 

let tee (f: 'T -> unit) (result: Result<'T, 'Error>) : Result<'T, 'Error> =
    match result with
    | Ok value ->
        f value
        Ok value
    | Error e -> Error e

let teeError (f: 'Error -> unit) (result: Result<'T, 'Error>) : Result<'T, 'Error> =
    match result with
    | Ok value -> Ok value
    | Error e ->
        f e
        Error e

// Usage in a pipeline
let processWithLogging (input: string) =
    input
    |> validateEmail
    |> tee (fun email -> printfn "Validated email: %s" email)
    |> Result.map (fun email -> email.ToLower())
    |> teeError (fun err -> eprintfn "Error occurred: %A" err)
    |> Result.bind (fun email -> 
        // continue processing...
        Ok (email, System.DateTime.UtcNow)
    )

Conclusion

Error handling patterns in F# represent a paradigm shift from exception-oriented programming to type-driven, explicit failure management. By encoding errors directly in your type signatures using Option and Result, you gain compiler-enforced exhaustiveness, seamless composability through map and bind, and the ability to build rich error contexts that carry meaningful information through your application. The railway-oriented programming model, combined with computation expressions for readability and applicative patterns for error accumulation, provides a complete toolkit for handling failures gracefully. By catching exceptions at system boundaries and keeping core logic pure, you create codebases that are easier to reason about, test, and maintain. The patterns covered here—from simple Option chaining to complex AsyncResult composition—form the foundation of robust, production-grade F# applications.

🚀 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