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

  1. Ensure the concrete subclass constructor always assigns this.inequalityHandling from a valid InequalityHandling constant (RESET, RELOCATE, PASS_NULL, STOP_EVERYONE)
  2. Print/inspect the iterator's inequalityHandling value when the exception message shows null
  3. 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

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


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)