title: When to throw IllegalStateException vs IllegalArgumentException?
body: <p>Let's start with the Javadocs:</p>
  <p><a href="https://docs.oracle.com/javase/8/docs/api/java/lang/IllegalStateException.html" rel="nofollow noreferrer">IllegalStateException</a></p>
  <blockquote>
  <p>Signals that a method has been invoked at an illegal or inappropriate
  time. In other words, the Java environment or Java application is not
  in an appropriate state for the requested operation.</p>
  </blockquote>
  <p><a href="https://docs.oracle.com/javase/8/docs/api/java/lang/IllegalArgumentException.html" rel="nofollow noreferrer">IllegalArgumentException</a></p>
  <blockquote>
  <p>Thrown to indicate that a method has been passed an illegal or
  inappropriate argument.</p>
  </blockquote>
  <p>The problem with the above is that they are very black and white. Consider a use case where a method is parsing a file provided by the caller. The file exists, is readable, and is in the correct format. However, some content in the file is non-compliant with the business rules. What would be an appropriate exception to throw in this case - <code>IllegalStateException</code> or <code>IllegalArgumentException</code>?</p>
  <p>Looking at various libraries that provide assertions, like Guava <a href="https://google.github.io/guava/releases/23.0/api/docs/com/google/common/base/Preconditions.html" rel="nofollow noreferrer">Preconditions</a> or Spring <a href="https://docs.spring.io/spring/docs/4.3.12.RELEASE/javadoc-api/index.html?org/springframework/util/Assert.html" rel="nofollow noreferrer">Assert</a>, it appears that there is no consensus. There are some good discussions <a href="https://stackoverflow.com/questions/12698275/whats-the-intended-use-of-illegalstateexception">here</a> and <a href="https://stackoverflow.com/questions/15208544/when-should-an-illegalargumentexception-be-thrown">here</a>, but none provide a conclusive answer to the common use case I stated above.</p>