languagetool-org/languagetool · error · IllegalArgumentException

Wrong position in WhitespaceCheckFilter: " + pos + ", must b

Error message

Wrong position in WhitespaceCheckFilter: " + pos + ", must be 1 to " + patternTokens.length

What it means

WhitespaceCheckFilter.acceptRuleMatch validates the 'position' argument of a whitespace-check XML rule. This IllegalArgumentException is thrown when the configured position is less than 1 or greater than the number of pattern tokens, since it indexes into patternTokens.

Source

Thrown at languagetool-core/src/main/java/org/languagetool/rules/WhitespaceCheckFilter.java:35

 * USA
 */
package org.languagetool.rules;

import java.util.List;
import java.util.Map;

import org.languagetool.AnalyzedTokenReadings;
import org.languagetool.rules.patterns.RuleFilter;

public class WhitespaceCheckFilter extends RuleFilter  {

  @Override
  public RuleMatch acceptRuleMatch(RuleMatch match, Map<String, String> arguments, int patternTokenPos,
                                   AnalyzedTokenReadings[] patternTokens, List<Integer> tokenPositions) {
    String wsChar = getRequired("whitespaceChar", arguments);
    int pos = Integer.parseInt(getRequired("position", arguments));
    if (pos < 1 || pos > patternTokens.length) {
      throw new IllegalArgumentException("Wrong position in WhitespaceCheckFilter: " + pos + ", must be 1 to " + patternTokens.length);
    }
    if (!patternTokens[pos - 1].getWhitespaceBefore().equals(wsChar)) {
      return match;
    } else {
      return null;
    }
  }

}

View on GitHub (pinned to 2e990059ce)

Solutions

1. Set 'position' in the rule XML to a value between 1 and the number of pattern tokens.
2. Remember positions are 1-based, so the first token is position 1.
3. If the pattern changed, recount tokens (including skipped/inflected placeholders) and update the position.

Example fix

// before (rule XML)
<filter class="...WhitespaceCheckFilter" position="0"/>
// after (rule XML)
<filter class="...WhitespaceCheckFilter" position="1"/>

// validate the rule before running LT
int pos = Integer.parseInt(attrs.get("position"));
if (pos < 1 || pos > patternTokenCount)
    throw new IllegalArgumentException("position must be 1.." + patternTokenCount);

try { rule.match(...); } catch (IllegalArgumentException e) { log.error("Bad whitespace_check rule config: " + e.getMessage()); }

When it happens

Trigger: A rule XML uses a whitespace_check filter with <position> set to 0, negative, or a value larger than the number of tokens matched by the rule's pattern.

Common situations: Authoring custom GrammarXML rules with an off-by-one position (positions are 1-based); a rule pattern was shortened without updating the filter's position attribute.

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

• Missing key 'date'
• Set 'no', 'regexp' and 'postag_regexp' for filter PartialPos
• Expected date in format 'yyyy-mm-dd': '" + dateString + "'
• grams must be between 1 and 5:
• Format error in file ${path}, line: ${line}

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