Skip to content
Tutorials Center
My learning

Topics

C# Reference ยท Exceptions and Diagnostics

The ArgumentException family

Reference for ArgumentException, ArgumentNullException and ArgumentOutOfRangeException in C#: when to throw them, ParamName, throw helpers and guard clauses.

The argument exceptions report that the caller passed a bad value to a method. ArgumentException is the general case: the value is invalid for some reason that is not simply null or out of range. Two subclasses are more specific: ArgumentNullException for a null argument that must not be null, and ArgumentOutOfRangeException for a value outside the allowed range.

All three carry ParamName, the name of the offending parameter, which makes the error message actionable. Throw them at the start of a public method (a guard clause), before doing any work, so the failure is reported at the real source of the problem.

C#
ArgumentNullException.ThrowIfNull(name);
ArgumentOutOfRangeException.ThrowIfNegative(age);

Try it

C# The three exception types

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

C# Throw helpers and range checks

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

Syntax

C#
public class ArgumentException : SystemException
{
    public ArgumentException();
    public ArgumentException(string? message);
    public ArgumentException(string? message, string? paramName);
    public ArgumentException(string? message, Exception? innerException);
    public virtual string? ParamName { get; }
    public static void ThrowIfNullOrEmpty(string? argument, string? paramName = null);
    public static void ThrowIfNullOrWhiteSpace(string? argument, string? paramName = null);
}

public class ArgumentNullException : ArgumentException
{
    public ArgumentNullException(string? paramName);
    public static void ThrowIfNull(object? argument, string? paramName = null);
}

public class ArgumentOutOfRangeException : ArgumentException
{
    public ArgumentOutOfRangeException(string? paramName, object? actualValue, string? message);
    public virtual object? ActualValue { get; }
    public static void ThrowIfNegative<T>(T value, string? paramName = null);
    public static void ThrowIfZero<T>(T value, string? paramName = null);
    public static void ThrowIfGreaterThan<T>(T value, T other, string? paramName = null);
    public static void ThrowIfLessThan<T>(T value, T other, string? paramName = null);
}
Name Description
message Explanation of what is wrong. Constructors of the subclasses add a standard text if you omit it.
paramName Name of the parameter. The ThrowIf... helpers fill it in automatically from the argument expression.
actualValue The value that was out of range (ArgumentOutOfRangeException only).
innerException The original exception, when wrapping.

Throw helpers throw if the check fails and do nothing otherwise.

Usage notes

  • Two constructor traps. new ArgumentException(message, paramName) takes the message first, while new ArgumentNullException(paramName) takes only the parameter name. Mixing them up puts the name in the message.
  • Use nameof. nameof(age) stays correct when you rename the parameter.
  • The helpers capture the expression. ThrowIfNull(name) reports name as the parameter without you typing it.
  • Validate before side effects. A guard clause at the top means a rejected call changes nothing.
  • Pick the right type. Null: ArgumentNullException. Number or index outside limits: ArgumentOutOfRangeException. Everything else wrong with an argument: ArgumentException. If the argument is fine but the object is in the wrong state, use InvalidOperationException.
  • Iterators and async methods throw late. Arguments of an yield return method or an async method are checked when enumeration starts or the task is awaited, unless you split the validation into an outer method.
  • Nullable annotations help. With nullable reference types enabled, the compiler warns when you pass null to a non-nullable parameter, but the runtime check is still needed for public APIs.
  • Do not catch these to fix them. They signal a caller bug; fix the call instead of catching.