deeplearning4j/deeplearning4j · error · ND4JIllegalStateException
Unknown InequalityHanding option was passed in:
Error message
Unknown InequalityHanding option was passed in:
What it means
BaseParallelDataSetIterator.hasNext() dispatches on the configured InequalityHandling strategy once some producers are depleted. If the inequalityHandling field does not match any known enum constant (typically null or an unrecognized value on this code path), the switch's default branch throws ND4JIllegalStateException('Unknown InequalityHanding option was passed in: ' + inequalityHandling).
Solutions
- Ensure the concrete subclass constructor always assigns this.inequalityHandling from a valid InequalityHandling constant (RESET, RELOCATE, PASS_NULL, STOP_EVERYONE)
- Print/inspect the iterator's inequalityHandling value when the exception message shows null
- Fix any serialization/config pipeline so the enum survives round-trips, and validate it in the constructor with Objects.requireNonNull
Example fix
// before
protected BaseParallelDataSetIterator(int numProducers) {
super(numProducers);
// inequalityHandling never set -> ND4JIllegalStateException in hasNext()
}
// after
public MyParallelIterator(int numProducers, InequalityHandling handling) {
super(numProducers);
this.inequalityHandling = Objects.requireNonNull(handling, "inequalityHandling");
} Defensive patterns
Strategy: validation
Validate before calling
Objects.requireNonNull(inequalityHandling, "inequalityHandling must be set");
EnumSet.of(InequalityHandling.RESET, InequalityHandling.RELOCATE,
InequalityHandling.PASS_NULL, InequalityHandling.STOP_EVERYONE)
.contains(inequalityHandling); // else reject before use Try / catch
try {
boolean more = parallelIterator.hasNext();
} catch (ND4JIllegalStateException e) {
// log inequalityHandling value; reconfigure iterator with a valid InequalityHandling enum constant
} Prevention
- Always pass a valid InequalityHandling constant (RESET/RELOCATE/PASS_NULL/STOP_EVERYONE) into the subclass constructor
- Add a constructor-time null check on inequalityHandling in custom subclasses
- Validate enum values survive any serialization/config round-trip
- Check the exception message — it prints the offending value, often null
When it happens
Trigger: hasNext() reached the switch because states are not allFalse and the current producer is depleted, while inequalityHandling is null (field never set because a subclass/constructor did not assign it) or holds an unexpected value; deserialization/serialization of the iterator dropping the enum value.
Common situations: Custom subclass of BaseParallelDataSetIterator forgetting to set inequalityHandling before first hasNext(); constructing the iterator via reflection/framework DI that skips the enum field; mixing DL4J versions where an enum constant was renamed so old serialized configs no longer match.
Understand the failure class
Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.
Related errors
- attachThread(int) should be called prior to this call
- Can't get value for non-ROC Metric
- Invalid rank for wordsNearest method
- Non-existent consumer was requested
- Non-existent consumer was requested
AI-assisted analysis of deeplearning4j/deeplearning4j@4c22ac5fe4 (2026-09-07).
Data as JSON: /api/errors/293f90dc14edccfc.
Report an issue: GitHub.
Appendix: source
Thrown at deeplearning4j/deeplearning4j-data/deeplearning4j-utility-iterators/src/main/java/org/deeplearning4j/datasets/iterator/parallel/BaseParallelDataSetIterator.java:114
if (states.allFalse())
return false;
}
return true;
}
case PASS_NULL: {
// we just return true here, no matter what's up
return true;
}
case STOP_EVERYONE: {
if (!states.allTrue())
return false;
return true;
}
default:
throw new ND4JIllegalStateException(
"Unknown InequalityHanding option was passed in: " + inequalityHandling);
}
}
public DataSet next() {
DataSet ds = nextFor(getCurrentProducerIndex());
stepForward();
return ds;
}
protected int getCurrentProducerIndex() {
return (int) (counter.get() % numProducers);
}
protected void stepForward() {
counter.getAndIncrement();
}
View on GitHub (pinned to 4c22ac5fe4)