languagetool-org/languagetool · error · IllegalStateException

listUnknownWords is set to false, unknown words not stored

Error message

listUnknownWords is set to false, unknown words not stored

What it means

JLanguageTool.getUnknownWords() returns the sorted list of unknown (not-in-dictionary) words collected during the last check() run. Unknown-word collection is opt-in via setListUnknownWords(true); when it is disabled the words are never stored, so calling getUnknownWords() throws IllegalStateException because there is no meaningful data to return.

Source

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

  protected void rememberUnknownWords(AnalyzedSentence analyzedText) {
    if (listUnknownWords) {
      AnalyzedTokenReadings[] atr = analyzedText.getTokensWithoutWhitespace();
      for (AnalyzedTokenReadings reading : atr) {
        if (!reading.isTagged()) {
          unknownWords.add(reading.getToken());
        }
      }
    }
  }

  /**
   * Get the alphabetically sorted list of unknown words in the latest run of one of the {@link #check(String)} methods.
   *
   * @throws IllegalStateException if {@link #setListUnknownWords(boolean)} has been set to {@code false}
   */
  public List<String> getUnknownWords() {
    if (!listUnknownWords) {
      throw new IllegalStateException("listUnknownWords is set to false, unknown words not stored");
    }
    List<String> words = new ArrayList<>(unknownWords);
    Collections.sort(words);
    return words;
  }

  // non-private only for test case
  static int countLineBreaks(String s) {
    int pos = -1;
    int count = 0;
    while (true) {
      int nextPos = s.indexOf('\n', pos + 1);
      if (nextPos == -1) {
        break;
      }
      pos = nextPos;
      count++;
    }

View on GitHub (pinned to 2e990059ce)

Solutions

1. Call tool.setListUnknownWords(true) before running check()
2. Re-check the text with a fresh JLanguageTool after enabling collection, since only the latest run's words are stored
3. Only call getUnknownWords() when the flag is known to be enabled

Example fix

// before
List<String> unknown = tool.getUnknownWords(); // IllegalStateException
// after
tool.setListUnknownWords(true);
tool.check("Your text here");
List<String> unknown = tool.getUnknownWords();

if (tool.getListUnknownWords()) { List<String> unknown = tool.getUnknownWords(); }

try { List<String> unknown = tool.getUnknownWords(); } catch (IllegalStateException e) { /* enable setListUnknownWords(true) and re-run */ }

When it happens

Trigger: Calling getUnknownWords() while listUnknownWords is false — the default or after explicitly calling setListUnknownWords(false).

Common situations: Developers calling getUnknownWords() on a default-configured JLanguageTool instance, or after reusing an instance whose listUnknownWords flag was reset/disabled, forgetting that collection is off by default.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• WrongParameterNumberException
• Unknown mode: <mode>
• Text checking was stopped due to too many errors (more than
• '${langCode}' is not a language code known to LanguageTool.
• Directory must contain at least '1grams', '2grams', and '3gr

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