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.
if (percent < 0 || percent > 100) { throw new IllegalArgumentException("percent must be 0..100 but was " + percent); }
Try it
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.
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
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
IllegalStateExceptioninstead. nullis different. For anullargument the convention isNullPointerException, usually viaObjects.requireNonNull. UseIllegalArgumentExceptionfor non-null but unacceptable values.- Index arguments have their own types:
IndexOutOfBoundsExceptionfor positions in lists, strings and arrays. - Validate at the boundary. Check arguments in public methods and constructors; private helpers can use
assertor 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.