languagetool-org/languagetool · error · IllegalArgumentException

grams must be between 1 and 5:

Error message

grams must be between 1 and 5: 

What it means

ConfusionProbabilityRule's constructor validates the n-gram order parameter 'grams' and throws this IllegalArgumentException when it is outside the supported 1..5 range, because the underlying language model lookup logic only supports up to 5-grams.

Source

Thrown at languagetool-core/src/main/java/org/languagetool/rules/ngrams/ConfusionProbabilityRule.java:109

   * @since 4.7
   */
  public ConfusionProbabilityRule(ResourceBundle messages, LanguageModel languageModel, Language language, int grams, List<String> exceptions) {
    this(messages, languageModel, language, grams, exceptions, Collections.emptyList());
  }

  public ConfusionProbabilityRule(ResourceBundle messages, LanguageModel languageModel, Language language, int grams,
                                  List<String> exceptions, List<List<PatternToken>> antiPatterns) {
    super(messages);
    setCategory(Categories.TYPOS.getCategory(messages));
    setLocQualityIssueType(ITSIssueType.NonConformance);
    for (String filename : getFilenames()) {
      String path = "/" + language.getShortCode() + "/" + filename;
      this.wordToPairs.putAll(confSetCache.getUnchecked(new PathAndLanguage(path, language)));
    }
    this.lm = Objects.requireNonNull(languageModel);
    this.language = Objects.requireNonNull(language);
    if (grams < 1 || grams > 5) {
      throw new IllegalArgumentException("grams must be between 1 and 5: " + grams);
    }
    this.grams = grams;
    this.exceptions = exceptions;
    this.antiPatterns = makeAntiPatterns(antiPatterns, language);
  }

  @NotNull
  protected List<String> getFilenames() {
    return Arrays.asList("confusion_sets.txt");
  }

  @Override
  public String getId() {
    return RULE_ID;
  }

  @Override
  public int estimateContextForSureMatch() {

View on GitHub (pinned to 2e990059ce)

Solutions

1. Pass a grams value between 1 and 5 (typically 3 for trigram models).
2. Clamp or validate the value before constructing the rule, e.g. Math.max(1, Math.min(5, grams)).
3. Check where grams comes from (config file/flag) and fix the source value.

Example fix

// before
new ConfusionProbabilityRule(messages, lm, language, grams, exceptions, antiPatterns);
// after
int safeGrams = Math.max(1, Math.min(5, grams));
new ConfusionProbabilityRule(messages, lm, language, safeGrams, exceptions, antiPatterns);

// clamp grams before constructing the rule
if (grams < 1 || grams > 5)
    throw new IllegalArgumentException("grams must be 1..5, got " + grams);
int safeGrams = Math.max(1, Math.min(5, grams));

try { new ConfusionProbabilityRule(msgs, lm, lang, grams, exc, ap); } catch (IllegalArgumentException e) { log.error("Config error: " + e.getMessage()); }

When it happens

Trigger: Constructing ConfusionProbabilityRule with grams = 0, negative, or > 5.

Common situations: Tuning n-gram order in custom confusion-rule setups for languages without a 5-gram model; passing a config value or CLI flag unvalidated; confusing n-gram order with window size.

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

• Wrong position in WhitespaceCheckFilter: " + pos + ", must b
• Missing key 'date'
• Expected date in format 'yyyy-mm-dd': '" + dateString + "'
• Confusion set must be of size 2:
• No alternative found for:

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