A generic "Exception" tells you something broke. A custom exception tells you exactly what — and gives the caller a fighting chance to react.

In the last lesson, you saw a payment method that can fail because an account doesn't have enough money. You could report that with a plain InvalidOperationException("Not enough funds"). It would work. But now imagine the caller wants to handle this specific failure differently from every other possible failure — maybe by prompting the user to add funds, rather than showing a generic "something went wrong" error.

With a generic exception type, the caller has no reliable way to distinguish "insufficient funds" from "account frozen" from "network timeout" without fragile string-matching on the message. What's needed is a type that says exactly what happened — an InsufficientFundsException, distinguishable at compile time from anything else.

In this lesson, you'll learn how to design and throw your own exception types, the crucial difference between throw and throw ex, and how exception filters let you catch based on more than just type.

What Is It?

The Simple Explanation

A custom exception is just a class you write yourself that derives from System.Exception (or a more specific built-in exception type). Once it exists, you can throw an instance of it exactly like any built-in exception — and callers can catch it by that specific type.

The Technical Definition

Creating a custom exception means declaring a class — conventionally named ending in Exception — that inherits from System.Exception or an appropriate subclass. By convention it exposes the standard constructors (parameterless, message-only, message-plus-inner-exception), and it may add extra properties to carry structured data about the failure beyond what a plain string message can hold.

Why Does It Exist?

The Problem

Built-in exception types are deliberately generic — InvalidOperationException, ArgumentException — because they're meant to cover countless unrelated scenarios across the entire .NET ecosystem. If every failure in your domain used the same generic type, callers trying to handle one specific case would have no clean way to distinguish it from every other case that also happens to throw InvalidOperationException.

The Need

Your application's domain has its own failure modes — insufficient funds, an out-of-stock product, an expired session — that deserve their own identity. Callers need to be able to say "catch this exact kind of failure" without resorting to inspecting message text.

The Solution — Domain-Specific Exception Types

By defining InsufficientFundsException as its own class, you give it a permanent, compiler-checked identity. Callers write catch (InsufficientFundsException ex) and know precisely what they're handling. You can also attach structured data — like the shortfall amount — as real typed properties instead of parsing it back out of a sentence.

Big Picture

Custom exceptions slot directly into the hierarchy you learned about in the previous lesson — they don't replace it, they extend it:

How It Works

public class InsufficientFundsException : Exception
{
    public decimal AvailableBalance { get; }
    public decimal RequestedAmount { get; }

    public InsufficientFundsException(decimal availableBalance, decimal requestedAmount)
        : base($"Cannot withdraw {requestedAmount:C}; only {availableBalance:C} available.")
    {
        AvailableBalance = availableBalance;
        RequestedAmount = requestedAmount;
    }
}

public void Withdraw(decimal amount)
{
    if (amount > _balance)
        throw new InsufficientFundsException(_balance, amount);

    _balance -= amount;
}

try
{
    account.Withdraw(500m);
}
catch (InsufficientFundsException ex)
{
    Console.WriteLine($"Short by {ex.RequestedAmount - ex.AvailableBalance:C}");
}

throw vs. throw ex — the stack trace trap

Inside a catch block, you can re-throw the caught exception two different-looking ways that behave very differently:

Exception filters — catching based on more than type

Sometimes you want to catch a specific type only under certain conditions. A when clause on a catch block lets you add that condition without giving up the ability to fall through to a later catch block if it doesn't match:

Unlike an if statement inside the catch block, a filter that evaluates to false means this catch block is skipped entirely — the runtime moves on to check the next catch block, exactly as if the type hadn't matched at all. This also matters for debugging: filters run before the stack unwinds, so a debugger attached at the throw site can still inspect the original call stack even while the filter condition is being evaluated.

Simple Example

A minimal custom exception with just a message — the simplest form:

Notice the standard shape: a class ending in Exception, deriving from Exception, building a clear message via the base constructor, and exposing one extra property (Sku) that a caller can inspect programmatically instead of parsing the message.

Real-World Example

A payment-processing method in an e-commerce checkout flow, using a custom exception with an inner exception to preserve the original cause:

The innerException parameter (available on Exception's standard constructors, and worth including on your own custom types) is important here — it means ex.InnerException still points back to the original GatewayTimeoutException, so nothing about the root cause is lost even though the caller only needs to catch PaymentDeclinedException.

Under the Hood

Why does throw; preserve the stack trace while throw ex; resets it? Every exception object carries a StackTrace property that the CLR populates. Specifically, the runtime records the trace starting from where the exception was thrown — not where it was created (those are usually the same statement, but not always).

This is exactly why production logging that relies on ex.StackTrace becomes much less useful the moment throw ex; is used anywhere in the call chain — the trace no longer points at the actual bug.

Common Confusion

1. "I should derive from ApplicationException"

Older guidance suggested deriving custom exceptions from System.ApplicationException to distinguish "your" exceptions from framework ones. Microsoft has since reversed that advice — there's no reliable value in the distinction, and modern .NET guidance is simply to derive directly from Exception (or a more specific existing type when your failure genuinely is a special case of one, e.g. deriving from ArgumentException for a domain-specific argument problem).

2. Exception filters vs. an if statement inside catch

You could write catch (Exception ex) { if (!condition) throw; ... } to approximate a filter — but it's not the same. That version still enters the catch block (and any debugger breakpoint set on it) even when the condition doesn't hold, and it re-throws using... well, hopefully a bare throw;. A when filter skips the catch block entirely when the condition is false, which is both cleaner and lets a later, more appropriate catch block take over immediately.

3. "throw ex is only a style preference"

It looks stylistic, but it's a real functional difference — it changes what information is available afterward. Treat this as a hard rule, not a preference: use bare throw; when re-throwing the same exception, always.

Common Mistakes

Mistake 1 — Creating a custom exception type for every tiny variation

A separate exception class for CardExpiredException, CardNumberInvalidException, CardCvvInvalidException... when a single InvalidCardException with a Reason enum property would serve callers just as well with far less ceremony. Reserve a brand-new type for cases callers genuinely need to handle differently — not for every distinct message.

Mistake 2 — Losing the inner exception when wrapping

Wrong:

Correct: always pass the caught exception as the inner exception.

Mistake 3 — Using throw ex out of habit

Many developers write throw ex; without realizing it resets the stack trace, simply because it "reads more naturally" as re-throwing the variable they just caught. Train yourself to reach for the bare throw; whenever the intent is "let this exception continue on its way, unchanged."

When Should I Use It?

Create a custom exception when:

• Callers plausibly need to handle this failure differently from other failures.
• You need to carry structured data about the failure (amounts, IDs, codes) beyond a message string.
• The failure represents a genuine, named concept in your business domain — insufficient funds, expired session, out of stock.

A built-in exception is enough when:

• It's a generic argument or state problem that an existing type (ArgumentException, InvalidOperationException) already describes accurately.
• No caller anywhere in the codebase needs to catch this specific case differently from any other.

Mental Model

Key Takeaway

Check Your Understanding

You've learned how to create your own exception types and re-throw them safely. Let's test how well it stuck.

You can now design your own exception types, throw and re-throw them safely, and filter catch blocks with precision. Next, we shift from errors to another everyday reality of real applications: reading and writing files.

dotnetmadeeasy.com — Learn C# and .NET, the right way.