Skip to content
Tutorials Center
My learning

Topics

Java Reference ยท java.lang

IllegalArgumentException

Reference for IllegalArgumentException: reject invalid method arguments with clear messages, its subclasses, and how it differs from IllegalStateException.

IllegalArgumentException signals that a method received an argument it cannot accept, even though the argument has the right type. A negative size, an empty name where one is required, a percentage of 150: the call itself is wrong, and retrying with the same value can never succeed. It extends RuntimeException, so it is unchecked.

The JDK throws it in many places (Thread.setPriority, String.repeat(-1), ArrayList(-1), Enum.valueOf), and your own methods should throw it to validate public inputs. Its best-known subclass is NumberFormatException.

Java
if (percent < 0 || percent > 100) {
    throw new IllegalArgumentException("percent must be 0..100 but was " + percent);
}

Try it

Java Validating arguments

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 IO.readln() or a Scanner), it gets the next line from this box.

Java Thrown by the JDK, and a subclass

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 IO.readln() or a Scanner), it gets the next line from this box.

Syntax

Java
public class IllegalArgumentException extends RuntimeException
Constructor Description
IllegalArgumentException() No message.
IllegalArgumentException(String message) Detail message.
IllegalArgumentException(String message, Throwable cause) Message and cause.
IllegalArgumentException(Throwable cause) Wraps a cause.

Known subclasses: NumberFormatException, InvalidPathException, PatternSyntaxException, and IllegalFormatException (the family behind String.format mistakes).

Usage notes

  • Say what was wrong and what was given. "age must be 0..150 but was -3" beats "invalid age". Include the offending value, and avoid secrets in messages.
  • Argument, not state. If the arguments are fine but the object is in the wrong condition (a closed connection, a started thread), throw IllegalStateException instead.
  • null is different. For a null argument the convention is NullPointerException, usually via Objects.requireNonNull. Use IllegalArgumentException for non-null but unacceptable values.
  • Index arguments have their own types: IndexOutOfBoundsException for positions in lists, strings and arrays.
  • Validate at the boundary. Check arguments in public methods and constructors; private helpers can use assert or trust the caller.
  • Do not catch it to recover. It reports a bug in the caller. At a user-input boundary, validate before calling or catch it and turn it into a friendly message.
  • Records can validate in a compact constructor and throw it, so invalid instances never exist.
  • Prefer a specific subclass when the standard library offers one that fits.