languagetool-org/languagetool · error · IllegalArgumentException

'skip' should be between -1 and ${Byte.MAX_VALUE}

Error message

'skip' should be between -1 and ${Byte.MAX_VALUE}

What it means

PatternToken.setSkipNext(int) validates that the skip scope is -1 (infinite) or between 0 and Byte.MAX_VALUE (127), throwing IllegalArgumentException otherwise. LanguageTool stores skip as a byte, so larger values are unsupported by design. Negative values other than -1 are also invalid.

Source

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

   * The minimum number of times the element needs to occur.
   */
  public int getMinOccurrence() {
    return hasFlag(MAY_BE_OMITTED_MASK) ? 0 : 1;
  }

  /**
   * The maximum number of times the element may occur.
   */
  public int getMaxOccurrence() {
    return maxOccurrence;
  }

  /**
   * @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

View on GitHub (pinned to 2e990059ce)

Solutions

1. Use -1 for unlimited skip instead of a large positive number.
2. Clamp the skip value to Byte.MAX_VALUE (127) before calling setSkipNext if your value is computed.
3. Check the rule XML: change skip attributes >127 to 127 or -1.
4. Validate user-supplied scope numbers at config load time with a range check.

Example fix

// before
pToken.setSkipNext(300);
// after
pToken.setSkipNext(300 > Byte.MAX_VALUE ? -1 : 300); // or skip="-1" in XML

public static int safeSkip(int i) {
  if (i < -1 || i > Byte.MAX_VALUE) throw new IllegalArgumentException("skip must be -1..127: " + i);
  return i;
}
// call: pToken.setSkipNext(safeSkip(userSkip));

boolean isValidSkip(int i) { return i >= -1 && i <= Byte.MAX_VALUE; }

try {
  token.setSkipNext(skip);
} catch (IllegalArgumentException e) {
  token.setSkipNext(-1); // fall back to unlimited
}

When it happens

Trigger: Calling setSkipNext(-2) or setSkipNext(128 or more); also via pattern builders/XML when a rule's skip="200" is parsed during build() (see testInfiniteSkip).

Common situations: Writing a rule that intends 'skip many tokens' with an oversized skip value; computing skip dynamically from a number that exceeds 127; typos like skip="1000" intending 'unlimited' instead of skip="-1".

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

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

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