stanfordnlp/CoreNLP · error · IllegalArgumentException

Invalid value for useUnknownWordSignatures:

Error message

Invalid value for useUnknownWordSignatures:

What it means

ArabicUnknownWordModel validates the unknown-word signature level inherited from BaseUnknownWordModel (from Options LexOptions.useUnknownWordSignatures). Arabic supports only a limited range of signature levels (MIN_UNKNOWN..MAX_UNKNOWN); a value outside that range is rejected in the constructor with IllegalArgumentException.

Solutions

  1. Set useUnknownWordSignatures to a value within the Arabic-supported range (0..5; check MIN_UNKNOWN/MAX_UNKNOWN constants)
  2. Omit the flag to use the default unknown word signature level
  3. If loading a serialized model with bad options, retrain or fix the options file

Example fix

// before
java ... -unknownWordSignatures 7
// after
java ... -unknownWordSignatures 5
Defensive patterns

Strategy: validation

Validate before calling

int lvl = op.lexOptions.useUnknownWordSignatures;
if (lvl < ArabicUnknownWordModel.MIN_UNKNOWN || lvl > ArabicUnknownWordModel.MAX_UNKNOWN) {
  op.lexOptions.useUnknownWordSignatures = 0; // or clamp to range
}

Try / catch

try {
  ArabicUnknownWordModel m = new ArabicUnknownWordModel(op, lex, wordIndex, tagIndex, unSeen);
} catch (IllegalArgumentException e) {
  op.lexOptions.useUnknownWordSignatures = 0;
  ArabicUnknownWordModel m = new ArabicUnknownWordModel(op, lex, wordIndex, tagIndex, unSeen);
}

Prevention

When it happens

Trigger: Constructing the model with options where useUnknownWordSignatures is set (e.g. via -unknownWordSignatures N on the command line or a loaded model options block) to a number outside the Arabic-supported range.

Common situations: Reusing English unknown-word option values with an Arabic model; editing serialized model options or training flags without checking Arabic's supported levels.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

AI-assisted analysis of stanfordnlp/CoreNLP@1b7edd19c4 (2026-09-10). Data as JSON: /api/errors/fc787b875499aa5b. Report an issue: GitHub.

Appendix: source

Thrown at src/edu/stanford/nlp/parser/lexparser/ArabicUnknownWordModel.java:40

  private static final long serialVersionUID = 4825624957364628771L;

  private static final int MIN_UNKNOWN = 6;

  private static final int MAX_UNKNOWN = 10;

  protected final boolean smartMutation;
  protected final int unknownSuffixSize;
  protected final int unknownPrefixSize;


  public ArabicUnknownWordModel(Options op, Lexicon lex,
                                Index<String> wordIndex,
                                Index<String> tagIndex,
                                ClassicCounter<IntTaggedWord> unSeenCounter) {
    super(op, lex, wordIndex, tagIndex, unSeenCounter, null, null, null);
    if (unknownLevel < MIN_UNKNOWN || unknownLevel > MAX_UNKNOWN) {
      throw new IllegalArgumentException("Invalid value for useUnknownWordSignatures: " + unknownLevel);
    }
    this.smartMutation = op.lexOptions.smartMutation;
    this.unknownSuffixSize = op.lexOptions.unknownSuffixSize;
    this.unknownPrefixSize = op.lexOptions.unknownPrefixSize;
  }

  /**
   * This constructor creates an UWM with empty data structures.  Only
   * use if loading in the data separately, such as by reading in text
   * lines containing the data.
   */
  public ArabicUnknownWordModel(Options op, Lexicon lex,
                                Index<String> wordIndex,
                                Index<String> tagIndex) {
    this(op, lex, wordIndex, tagIndex, new ClassicCounter<>());
  }

  @Override

View on GitHub (pinned to 1b7edd19c4)