# The Value of Custom Exceptions

> Custom exceptions in C# express errors in your domain's language and are more informative than built-in ones. Learn how to create them and test them.

- URL: https://blog.nimblepros.com/blogs/the-value-of-custom-exceptions/
- Author: [Scott DePouw](https://blog.nimblepros.com/authors/scott/)
- Published: 2025-08-25
- Updated: 2026-11-06
- Categories: [Software Development](https://blog.nimblepros.com/categories/software-development/)
- Publisher: [NimblePros](https://blog.nimblepros.com/)

---

Exceptions are thrown in code to indicate something went wrong. The reason we have exceptions instead of merely letting a program crash with a non-zero return code is to garner information on why something bad happened. Most programming languages have some form of unexpected error fact gathering, from exceptions to [panicking](https://docs.rust-embedded.org/book/start/panicking.html), as they are a vital instrument in diagnosing the causes of unexpected behavior.

Most languages offer extensibility to these exceptions, and C# is no... exception! Out of the box there are plenty of exception types that are available to use and are thrown by the language itself. Access an array with an invalid index? `IndexOutOfRangeException`. Access a property, method, field, or something else off a null object? You get the infamous `NullReferenceException` (infamous in that, for the longest time, it provided not much detail to help track down the source of the error). Something not finished? `NotImplmentedException` communicates this clearly.

While it can feel just fine to stick to the out-of-the-box exception types, a lot more value can come in the form of custom exception types, and it's a breeze to create and maintain them in C#. Custom exceptions allow communication of errors using [domain terminology](https://deviq.com/domain-driven-design/domain/) of an application and are easy to unit test.

## Expressing Errors with Application Domain Terms

Say there's a simple banking application, with a `Deposit(decimal amount)` method, with a business rule of "the provided amount must be greater than 0." We could use a native exception to throw an error when this rule is violated:

```csharp
public void Deposit(decimal amount)
{
  if (amount <= 0) throw new ArgumentOutOfRangeException($"Deposit amount must be greater than 0. Given {amount}");
  // Deposit the amount.
}
```

If we dive into this exception's stack trace or peek into its details we'd find the error. But instead of relying on magic strings or having to dive past the native exception type, why not just express the error using domain terminology? Let's update our method with a custom exception instead.

```csharp
// Define a custom exception in its own file
public class DepositAmountMustBePositiveException(decimal invalidAmount) 
  : ArgumentOutOfRangeException($"Deposit amount must be greater than 0. Given {invalidAmount}");

// Back in our class
public void Deposit(decimal amount)
{
  if (amount <= 0) throw new DepositAmountMustBePositiveException(amount);
  // Deposit the amount.
}
```

What have we accomplished?

- The exception itself informs us exactly what went wrong, without having to dive into details.
- If we are checking deposit amounts anywhere else for any other reason, we now can re-use the same exception without having to copy and paste the error string
  - This makes updating easier too. Say we wanted to express the invalid amount using currency formatting instead of a raw value. Instead of having to chase down every instance of this check, we can update the exception class.
- Instead of a generic "Argument out of Range" error, we are *expressing our error using our domain terms*.
- By making our exception inherit from `ArgumentOutOfRangeException`, we still communicate the same basic problem, except we give *context*.
  - Any existing tests or business logic relying on this specific exception type will still work, as `DepositAmountMustBePositiveException` is still of type `ArgumentOutOfRangeException`.

As illustrated above, defining a custom exception type is trivial: Inherit from `Exception` (or a more specific derivative), optionally defining a custom message to pass along as well.

## Testing Custom Exceptions

There are two kinds of unit tests typically associated with custom exceptions:

- Testing the exception data itself, for things like data points or messaging that must be included.
- Testing usages of it within the application, ensuring it's thrown in the correct circumstances.

Taking a look at our custom `DepositAmountMustBePositiveException`, we may wish to assert that the message contains the invalid deposit amount value. Since exceptions are nothing more than classes, a test can simply instantiate a new instance of the exception class, and assert its `Message` string contains the desired value.

When testing our class with the `Deposit` method, we would feed it several invalid values (e.g. `0m`, `-0.01m`, `-10.55m`) and assert that when calling `Deposit()` it throws, specifically, our custom `DepositAmountMustBePositiveException`. 

Given that C# itself, or other code, could throw the out-of-the-box `ArgumentOutOfRangeException`, it's possible that our testing could contain false positives! If we stick to custom exceptions, the odds of that occurring are reduced drastically. The reality is that very few spots, perhaps just one, will ever throw `DepositAmountMustBePositiveException`. And since custom exceptions are trivial to create, it's completely fine to define a custom exception type that will be used in just that one instance.

## Don't Be Shy: Make Custom Exceptions!

As established, custom exception types are trivial to create and maintain. You might find yourself making a lot once you internalize this, and that's cool. Expressing errors on your own (domain) terms leads to errors being discovered and fixed more quickly. It leads to tests being easier to read, write, and avoid false positives. It allows compartmentalization of error data and messaging, avoiding having to duplicate strings and formatting across your application. Get your hands dirty and create some custom exceptions!
