What causes "Unknown mode: " in languagetool-org/languagetool?

Use Mode.ALL or Mode.TEXTLEVEL_ONLY, the supported modes for this code path

languagetool-org/languagetool · error · IllegalArgumentException

Unknown mode: <mode>

Error message

Unknown mode: <mode>

What it means

JLanguageTool.check() dispatches on the configured Mode (e.g. ALL, TEXTLEVEL_ONLY); if the mode variable holds a value the switch/if-chain does not recognize, it throws IllegalArgumentException. This guards against enum values added later that this code path does not yet handle.

Source

Thrown at languagetool-core/src/main/java/org/languagetool/JLanguageTool.java:2120

    public CheckResults call() throws Exception {
      List<RuleMatch> ruleMatches = new ArrayList<>();
      List<Range> ignoreRanges = new ArrayList<>();
      List<ExtendedSentenceRange> extendedSentenceRanges = new ArrayList<>();
      if (mode == Mode.ALL) {
        ruleMatches.addAll(getTextLevelRuleMatches());
        CheckResults otherRuleMatches = getOtherRuleMatches(toneTags);
        ruleMatches.addAll(otherRuleMatches.getRuleMatches());
        ignoreRanges.addAll(otherRuleMatches.getIgnoredRanges());
        extendedSentenceRanges.addAll(otherRuleMatches.getExtendedSentenceRanges());
      } else if (mode == Mode.ALL_BUT_TEXTLEVEL_ONLY) {
        CheckResults otherRuleMatches = getOtherRuleMatches(toneTags);
        ruleMatches.addAll(otherRuleMatches.getRuleMatches());
        ignoreRanges.addAll(otherRuleMatches.getIgnoredRanges());
        extendedSentenceRanges.addAll(otherRuleMatches.getExtendedSentenceRanges());
      } else if (mode == Mode.TEXTLEVEL_ONLY) {
        ruleMatches.addAll(getTextLevelRuleMatches());
      } else {
        throw new IllegalArgumentException("Unknown mode: " + mode);
      }
      // can't call applyCustomRuleFilters here, done in performCheck ->
      // should run just once w/ complete list of matches
      return new CheckResults(ruleMatches, ignoreRanges, extendedSentenceRanges);
    }

    private List<RuleMatch> getTextLevelRuleMatches() throws IOException {
      List<RuleMatch> ruleMatches = new ArrayList<>();
      List<AnalyzedSentence> analyzedSentences = null;
      for (Rule rule : rules.allRules()) {
        if (rule instanceof TextLevelRule && paraMode != ParagraphHandling.ONLYNONPARA) {
          if (checkCancelledCallback != null && checkCancelledCallback.checkCancelled()) {
            break;
          }
          if (analyzedSentences == null) {
            analyzedSentences = sentences.stream().map(s -> s.analyzed).collect(Collectors.toList());
          }
          RuleMatch[] matches = ((TextLevelRule) rule).match(analyzedSentences, annotatedText);

View on GitHub (pinned to 2e990059ce)

Solutions

Use Mode.ALL or Mode.TEXTLEVEL_ONLY, the supported modes for this code path
Upgrade LanguageTool so the code recognizes your Mode value
Check for null mode before calling check()

Example fix

// before
lt.setMode(mode); // mode is an unrecognized value
lt.check(text); // IllegalArgumentException: Unknown mode
// after
lt.setMode(Mode.ALL);
lt.check(text);

Defensive patterns

Strategy: validation

Validate before calling

if (mode == null || (mode != Mode.ALL && mode != Mode.TEXTLEVEL_ONLY)) throw new IllegalArgumentException("Unsupported mode: " + mode);

Try / catch

try { results = lt.check(text); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("Unknown mode")) { lt.setMode(Mode.ALL); results = lt.check(text); } }

Prevention

Only use Mode constants documented for your LanguageTool version
Avoid passing user input as a Mode; map strings to known constants explicitly
After upgrading LanguageTool, verify custom mode handling still exists

When it happens

Trigger: Running check() with a Mode value that is neither ALL nor TEXTLEVEL_ONLY in the dispatch path, e.g. ModeLoadingLoopMode confusion or a null/custom mode value.

Common situations: Passing Mode.BOTH or a mode constant from a different LanguageTool version that the current check pipeline does not implement; programming error rather than user input.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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