The API used to listen for list changes is error prone in the sense that the programmer has to follow a very specific coding pattern, or exceptions are thrown. For instance, if one forgets to invoke the change.next() method a generic IllegalStateException with no message is thrown.

I have had this exception in my log dozens of times, because it simply does not feel natural for me that a Change instance is also an iterator. Since it is probably too late at this point to fix this cumbersome and untraditional API design, I recommend you replace the different generic exceptions thrown by the API, with specific, helpful ones.

As an example, I suggest replacing

Caused by: java.lang.IllegalStateException
at com.sun.javafx.collections.NonIterableChange.checkState(NonIterableChange.java:101)

with

Caused by: ImproperListChangeUsageException: When listening for list changes you are required to implement a while loop what iterates over the changes using the change.next() method.
at com.sun.javafx.collections.NonIterableChange.checkState(NonIterableChange.java:101)

so that the programmer gets a hint to what is wrong.