languagetool-org/languagetool · error · IllegalArgumentException

minOccurrences must be 0 or 1: ${i}

Error message

minOccurrences must be 0 or 1: ${i}

What it means

PatternToken.setMinOccurrence(int) only accepts 0 or 1: the minimum-occurrence feature ('token may be omitted') is limited to a boolean-like choice, enforced by the MAY_BE_OMITTED_MASK flag. Any other value throws IllegalArgumentException. Higher minimums are not supported by this API.

Source

Thrown at languagetool-core/src/main/java/org/languagetool/rules/patterns/PatternToken.java:415

  }

  /**
   * @param i exception scope length.
   */
  public void setSkipNext(int i) {
    if (i < -1 || i > Byte.MAX_VALUE) {
      throw new IllegalArgumentException("'skip' should be between -1 and " + Byte.MAX_VALUE);
    }
    skip = (byte) i;
  }

  /**
   * The minimum number of times this element may occur.
   * @param i currently only {@code 0} and {@code 1} are supported
   */
  public void setMinOccurrence(int i) {
    if (i != 0 && i != 1) {
      throw new IllegalArgumentException("minOccurrences must be 0 or 1: " + i);
    }
    setFlag(MAY_BE_OMITTED_MASK, i == 0);
  }

  /**
   * The maximum number of times this element may occur.
   * @param i a number &gt;= 1 or {@code -1} for unlimited occurrences
   */
  public void setMaxOccurrence(int i) {
    if (i == 0) {
      throw new IllegalArgumentException("maxOccurrences may not be 0");
    }
    if (i < -1 || i > Byte.MAX_VALUE) {
      throw new IllegalArgumentException("maxOccurrences should be between -1 and " + Byte.MAX_VALUE + " but was: " + i);
    }
    maxOccurrence = (byte) i;
  }

View on GitHub (pinned to 2e990059ce)

Solutions

1. Restrict the value to 0 (may be omitted) or 1 (required) before calling.
2. For min>1 repetition, model it differently: use setMaxOccurrence with multiple token elements or restructure the rule pattern.
3. If parsing XML, map minOccurs>1 to repeated <token> elements or reject the rule at load time with a clear message.
4. Update to a LanguageTool version if newer semantics are needed, after checking the changelog.

Example fix

// before
pToken.setMinOccurrence(2);
// after
pToken.setMinOccurrence(1); // use 0 or 1 only; express min>1 via repeated tokens

if (minOccurrence != 0 && minOccurrence != 1) {
  throw new IllegalArgumentException("PatternToken supports min 0 or 1 only, got: " + minOccurrence);
}
pToken.setMinOccurrence(minOccurrence);

boolean isBoolLike(int i) { return i == 0 || i == 1; }

try {
  token.setMinOccurrence(min);
} catch (IllegalArgumentException e) {
  token.setMinOccurrence(1); // treat as required; log the unsupported config
}

When it happens

Trigger: Calling setMinOccurrence(2) or any value other than 0/1, directly or through PatternRuleBuilder/build() when parsing minOccurs attributes from rule XML (see testTwoZeroMinOccurrences).

Common situations: Rule authors writing minOccurs="2" expecting repetition support; programmatic builders translating generic quantifier semantics (min>1) into PatternToken; code generator emitting min counts from grammar specs.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• 'skip' should be between -1 and ${Byte.MAX_VALUE}
• maxOccurrences may not be 0
• maxOccurrences should be between -1 and ${Byte.MAX_VALUE} bu
• minOccurrence must be >= 0: ${minOccurrence}
• Set only 'weekDay' and 'date' for " + YMDDateCheckFilter.cla

AI-assisted analysis of languagetool-org/languagetool@2e990059ce (2026-09-06). Data as JSON: /api/errors/d6647287727b26e5. Report an issue: GitHub.