C# Throw Exception: Guard Clauses, Throw Expressions, Custom Exceptions

Catching exceptions is half of error handling; the other half is throwing the right one. A well chosen exception tells the caller exactly what went wrong and whether it was their mistake or the program's state. This page covers the throw side; try catch covers handling.

The throw statement and guard clauses

throw takes an exception object. Execution of the method stops there, and the exception looks for a handler up the call stack. The most common use is a guard clause: checks at the top of a method that reject invalid input before any work is done.

using System;

class Account
{
    public decimal Balance { get; private set; }
    public bool Frozen { get; set; }

    public void Withdraw(decimal amount)
    {
        if (amount <= 0)
            throw new ArgumentOutOfRangeException(nameof(amount), "Amount must be positive.");
        if (Frozen)
            throw new InvalidOperationException("The account is frozen.");
        if (amount > Balance)
            throw new InvalidOperationException("Insufficient funds.");

        Balance -= amount;
    }

    public void Deposit(decimal amount)
    {
        if (amount <= 0)
            throw new ArgumentOutOfRangeException(nameof(amount), "Amount must be positive.");
        Balance += amount;
    }
}

class Program
{
    static void Main()
    {
        var acct = new Account();
        acct.Deposit(100m);

        try
        {
            acct.Withdraw(-5m);
        }
        catch (ArgumentOutOfRangeException e)
        {
            Console.WriteLine(e.GetType().Name + " for parameter '" + e.ParamName + "'");
        }

        acct.Frozen = true;
        try
        {
            acct.Withdraw(20m);
        }
        catch (InvalidOperationException e)
        {
            Console.WriteLine(e.GetType().Name + ": " + e.Message);
        }

        Console.WriteLine("Balance: " + acct.Balance);
    }
}

Output:

ArgumentOutOfRangeException for parameter 'amount'
InvalidOperationException: The account is frozen.
Balance: 100

nameof(amount) produces the string "amount" and stays correct if the parameter is renamed. The argument exceptions store it in ParamName, which tools and logs use to point at the bad argument.

Guard clauses keep the rest of the method simple: past the checks, the code can assume valid input. They also fail at the point of the mistake instead of letting a bad value travel on and cause a confusing NullReferenceException three methods later.

Which exception type to throw

Reuse a built-in type when it describes the situation; callers already know how to handle it.

The line between the first three rows and InvalidOperationException is who needs to change something. An argument exception says "call this differently". InvalidOperationException says "the call was fine, but not now".

Do not throw Exception, SystemException or ApplicationException directly: callers cannot catch them without also catching everything else. Do not throw NullReferenceException, IndexOutOfRangeException or StackOverflowException yourself either; the runtime reserves those for actual bugs.

Throw expressions

Before C# 7, throw was only a statement. Since C# 7 it can also appear as an expression in three places, which turns common checks into one line:

using System;

class Customer
{
    private readonly string name;
    private readonly string email;

    public Customer(string name, string email)
    {
        this.name = name ?? throw new ArgumentNullException(nameof(name));       // after ??
        this.email = email.Contains("@")
            ? email
            : throw new ArgumentException("Not an email address.", nameof(email)); // in ?:
    }

    public string Name => name;

    public string Nickname => throw new NotImplementedException();                // expression body

    public override string ToString() => name + " <" + email + ">";
}

class Program
{
    static void Main()
    {
        Console.WriteLine(new Customer("Ana", "ana@example.com"));

        try
        {
            new Customer(null, "x@example.com");
        }
        catch (ArgumentNullException e)
        {
            Console.WriteLine("Null: " + e.ParamName);
        }

        try
        {
            new Customer("Ben", "ben.example.com");
        }
        catch (ArgumentException e)
        {
            Console.WriteLine(e.GetType().Name + ": " + e.ParamName);
        }
    }
}

Output:

Ana <ana@example.com>
Null: name
ArgumentException: email

Note that ArgumentNullException derives from ArgumentException, so a catch (ArgumentException) placed first would also catch the null case. The order of catch clauses matters for the same reason when you handle both.

ThrowIfNull and friends (.NET 6 and later)

Modern .NET adds static helpers that write the check and the throw for you, with the parameter name captured automatically:

public void Ship(Order order, int quantity, string address)
{
    ArgumentNullException.ThrowIfNull(order);                   // .NET 6
    ArgumentOutOfRangeException.ThrowIfNegativeOrZero(quantity); // .NET 8
    ArgumentException.ThrowIfNullOrWhiteSpace(address);          // .NET 8
    ObjectDisposedException.ThrowIf(disposed, this);             // .NET 7

    // ...
}

They behave the same as the hand-written if and throw, and they keep guard clauses to one line each. On older targets, write the if form shown earlier.

Writing a custom exception class

Create your own exception type when callers need to catch this specific failure separately, or when the handler needs data that a message string cannot carry well.

using System;

class InsufficientFundsException : Exception
{
    public decimal Balance { get; }
    public decimal Requested { get; }

    public InsufficientFundsException() { }

    public InsufficientFundsException(string message) : base(message) { }

    public InsufficientFundsException(string message, Exception inner) : base(message, inner) { }

    public InsufficientFundsException(decimal balance, decimal requested)
        : base("Cannot withdraw " + requested + " from a balance of " + balance + ".")
    {
        Balance = balance;
        Requested = requested;
    }
}

class Program
{
    static decimal balance = 40m;

    static void Withdraw(decimal amount)
    {
        if (amount > balance) throw new InsufficientFundsException(balance, amount);
        balance -= amount;
    }

    static void Main()
    {
        try
        {
            Withdraw(25m);
            Withdraw(25m);
        }
        catch (InsufficientFundsException e)
        {
            Console.WriteLine(e.Message);
            Console.WriteLine("Short by " + (e.Requested - e.Balance));
        }
    }
}

Output:

Cannot withdraw 25 from a balance of 15.
Short by 10

The conventions:

• The name ends in Exception.
• It derives from Exception (or from a more specific built-in type when it is a special case of one, such as InvalidOperationException).
• It has the three standard constructors: none, message, and message plus inner exception. Add your own constructors on top.
• Extra data goes in read-only properties, set in the constructor. A handler can then act on e.Requested instead of parsing the message.

Wrapping with an inner exception

When a low-level failure should surface as a higher-level one, wrap it. The original is kept as InnerException, so no information is lost:

using System;

class ConfigException : Exception
{
    public ConfigException(string message, Exception inner) : base(message, inner) { }
}

class Program
{
    static int ReadPort(string text)
    {
        try
        {
            return int.Parse(text);
        }
        catch (FormatException e)
        {
            throw new ConfigException("Setting 'port' must be a number, got '" + text + "'.", e);
        }
    }

    static void Main()
    {
        try
        {
            ReadPort("80a");
        }
        catch (ConfigException e)
        {
            Console.WriteLine(e.Message);
            Console.WriteLine("Caused by: " + e.InnerException.GetType().Name);
        }
    }
}

Output:

Setting 'port' must be a number, got '80a'.
Caused by: FormatException

The caller now deals in terms of configuration, which it understands, and logging e.ToString() prints the whole chain including the FormatException and its stack trace. Only wrap when you add meaning; wrapping every exception in a generic MyAppException just makes handlers dig through InnerException.

Throwing vs returning a result

Exceptions are for failures the caller does not expect in normal operation. For outcomes that are routine, such as a lookup that often finds nothing or user input that is often invalid, the .NET convention is the Try pattern: return bool and hand the value back through an out parameter.

public bool TryWithdraw(decimal amount, out string error)
{
    if (amount > Balance) { error = "Insufficient funds."; return false; }
    Balance -= amount;
    error = null;
    return true;
}

Many types offer both: int.Parse throws, int.TryParse returns false; dict[key] throws, dict.TryGetValue returns false. Throwing an exception costs far more than returning a value, so it should not sit on a path that runs thousands of times a second. See ref and out for out parameters.

Writing good messages

An exception message is read by a developer looking at a log. Make it state what was wrong and, where safe, the offending value: "Quantity must be between 1 and 99, got 0." beats "Invalid input." Write full sentences, and keep secrets such as passwords and tokens out of messages, since they end up in log files.

Common mistakes

• Throwing Exception itself. Callers cannot catch it selectively; use a specific type.
• Passing the message where the parameter name goes. new ArgumentNullException("name") takes the parameter name; the message comes second.
• Hard-coded parameter names. Use nameof(param) so renames keep them correct.
• Custom exceptions with no extra meaning. If a built-in type fits, use it.
• Losing the original error when wrapping. Always pass it as the inner exception.