Java IllegalArgumentException — What It Means & How to Fix It

What Does This Error Mean?

An IllegalArgumentException means a method received an argument value that is not acceptable — it is outside the expected range or violates the method's rules. For example, passing a negative number to a method that expects a positive one, or passing an empty string to a method that requires non-empty input. The method is telling you: 'I cannot work with what you gave me.'

Affected Models

Java 8
Java 11
Java 17
Java 21
All Java versions

Common Causes

Passing a negative number to a method that requires a positive value (like array sizes or timeouts)
Passing null to a method that explicitly does not accept null
Passing an empty string or blank value where meaningful content is required
A value is out of a valid range — for example, a month value of 13 or a percentage above 100
Passing incompatible or conflicting arguments — for example, a start date that is after the end date

How to Fix It

Read the error message carefully — it almost always describes the exact problem. For example: 'timeout value is negative' or 'fromIndex > toIndex'.

The method that threw the exception wrote that message specifically to help you understand what went wrong.
Find where the invalid value came from. Trace backwards from the method call: was the value hardcoded? Calculated? Comes from user input? Each source needs a different fix.

Use your debugger or add logging to print the value just before the method call to confirm what was actually passed.
Add input validation before calling the method. Check that the value is in the expected range and meets the method's requirements before you call it.

Example: if (size <= 0) throw new IllegalArgumentException('Size must be positive: ' + size); — validate early with a clear message.
If your own methods can receive bad arguments, add validation at the start of each method and throw IllegalArgumentException yourself with a descriptive message.

This follows the 'fail fast' principle — catch bad input at the entry point rather than letting it cause mysterious failures deeper in your code.
Use the Objects.checkIndex(), Math.clamp() (Java 21+), or Guava's Preconditions class to perform common range checks cleanly without writing repetitive if statements.

Example: Objects.checkIndex(index, array.length) throws an informative IndexOutOfBoundsException automatically if the index is invalid.

When to Call a Professional

IllegalArgumentException is always a code logic issue you can fix yourself. The error message usually explains exactly what was wrong with the argument. Focus on validating inputs before passing them to methods that could reject them.

Frequently Asked Questions

What is the difference between IllegalArgumentException and IllegalStateException?

IllegalArgumentException is about the input being wrong — the value you passed is not acceptable. IllegalStateException is about the object being in the wrong state — the method cannot run right now because of the object's current condition. Example: IllegalArgumentException if you pass -1 as a size. IllegalStateException if you try to read from a closed stream.

Should I use IllegalArgumentException or NullPointerException for null arguments?

Java convention favors NullPointerException for null arguments, especially since Java 14 added Objects.requireNonNull() which throws a clear NullPointerException. Some developers prefer IllegalArgumentException for null inputs to make it clear it was a caller mistake. Either is acceptable — consistency within your codebase matters more than which one you pick.

Is IllegalArgumentException checked or unchecked?

It is unchecked — it extends RuntimeException. You do not need to declare it with 'throws' or catch it with try/catch. This is appropriate because illegal arguments are programming errors that should be prevented, not recovered from at runtime.