IllegalStateException
Java Programming Language
Severity: ModerateWhat Does This Error Mean?
An IllegalStateException means you called a method at the wrong time — the object is not in a state where that operation is allowed. Think of it like trying to press 'pause' on a music player that has not started yet. The operation is valid in general, but right now the object is not ready for it. You need to do things in the correct order.
Affected Models
- Java 8
- Java 11
- Java 17
- Java 21
- All Java versions
Common Causes
- Calling Iterator.remove() without calling Iterator.next() first
- Trying to read from a Scanner or stream that has already been closed
- Starting a Thread that has already been started — a thread can only be started once
- Calling a method on a builder or state machine before the required setup steps have been completed
- Using an HttpURLConnection after it has been disconnected, or trying to write to a closed connection
How to Fix It
-
Read the error message — it usually says what is wrong with the current state. For example: 'No current element' or 'Connection already established'.
Then look at the stack trace to find which method threw it and which line in your code called that method.
-
Check the order of operations in your code. Many APIs require a specific sequence — for example, you must call open() before read(), or next() before remove() on an iterator.
Read the JavaDoc for the class you are using. It usually lists under which conditions each method is valid to call.
-
For iterator issues: always call iterator.next() before calling iterator.remove(). The iterator must have a 'current element' before you can remove it.
If you call remove() twice in a row without a next() in between, IllegalStateException is thrown because there is no current element to remove.
-
For resource issues (streams, connections, scanners): check whether the resource is still open before using it. Add a boolean flag to track state, or use try-with-resources to manage lifetime automatically.
try-with-resources (try (InputStream is = new FileInputStream(file)) { ... }) closes the resource automatically when the block ends, preventing use-after-close errors.
-
For Thread issues: never try to start a thread that has already run. If you need to run the task again, create a new Thread instance, or use an ExecutorService which handles reuse properly.
ExecutorService is the preferred approach for most multi-threaded Java — it manages thread lifecycle for you.
When to Call a Professional
IllegalStateException is always a fixable logic issue in your code. The error message usually describes what state is wrong. The fix is almost always about calling methods in the correct order — read the library's documentation for the expected sequence.
Frequently Asked Questions
How do I know what 'state' an object is in?
Many Java classes have a predictable lifecycle: closed/open, connected/disconnected, started/stopped. The JavaDoc for the class usually documents the valid states and which methods are allowed in each. If the class has an isClosed() or isConnected() method, use it to check state before calling risky operations.
Why does Java have both IllegalArgumentException and IllegalStateException?
They represent two different kinds of problems. IllegalArgumentException means the value you passed is wrong — the input is the issue. IllegalStateException means the object itself is in the wrong condition — the timing or sequence is the issue. Same method, different cause: one is about what you passed, the other is about when you called it.
Is IllegalStateException checked or unchecked?
It is unchecked — it extends RuntimeException. Java does not force you to catch it or declare it. It is meant to signal a programming logic error (calling methods out of order) rather than a recoverable runtime condition.