languagetool-org/languagetool · error · IllegalArgumentException

Common words path not found: ''

Error message

Common words path not found: ''

What it means

After registering a dynamic language, LanguageTool proactively instantiates a JLanguageTool and checks whether the language's 'common words' file (auto-derived from the language code/dictionary) exists, failing early with this IllegalArgumentException if it does not.

Source

Thrown at languagetool-server/src/main/java/org/languagetool/server/HTTPServerConfig.java:549

        if (!code.contains("-") && code.length() != 2 && code.length() != 3) {
          throw new IllegalArgumentException("code is supposed to be a 2 (or rarely 3) character code (unless it uses a format with variant, like xx-YY): '" + code + "'");
        }
        String nameKey = "lang-" + code;
        String name = props.getProperty(nameKey);
        String dictPathKey = "lang-" + code + "-dictPath";
        String dictPath = props.getProperty(dictPathKey);
        if (dictPath == null) {
          throw new IllegalArgumentException(dictPathKey + " must be set");
        }
        File dictPathFile = new File(dictPath);
        if (!dictPathFile.exists() || !dictPathFile.isFile()) {
          throw new IllegalArgumentException("dictionary file does not exist or is not a file: '" + dictPath + "'");
        }
        ServerTools.print("Adding dynamic spell checker language " + name + ", code: " + code + ", dictionary: " + dictPath);
        Language lang = Languages.addLanguage(name, code, new File(dictPath));
        // better fail early in case of misconfiguration, so use the language now:
        if (!new File(lang.getCommonWordsPath()).exists()) {
          throw new IllegalArgumentException("Common words path not found: '" + lang.getCommonWordsPath() + "'");
        }
        JLanguageTool lt = new JLanguageTool(lang);
        lt.check("test");
      }
    }
  }

  public void setLanguageModelDirectory(String langModelDir) {
    SuggestionsOrdererConfig.setNgramsPath(langModelDir);
    languageModelDir = new File(langModelDir);
    if (!languageModelDir.exists() || !languageModelDir.isDirectory()) {
      throw new RuntimeException("LanguageModel directory not found or is not a directory: " + languageModelDir);
    }
  }

  void setFasttextPaths(String fasttextModelPath, String fasttextBinaryPath) {
    fasttextModel = new File(fasttextModelPath);
    fasttextBinary = new File(fasttextBinaryPath);

View on GitHub (pinned to 2e990059ce)

Solutions

1. Check the path in the message and create/populate the expected common-words file (typically via extract of an org.languagetool language resource layout)
2. Verify the dictPath file is a valid hunspell/morfologik dictionary for the given language code
3. Run a `lt.check("test")` setup manually to surface the underlying resource-loading error

Language lang = Languages.addLanguage(name, code, dictFile);
if (!new File(lang.getCommonWordsPath()).exists()) {
  throw new IllegalStateException("Common words file missing: " + lang.getCommonWordsPath());
}

try {
  config.addDynamicLanguages(props);
} catch (IllegalArgumentException | IOException e) {
  LOG.error("Dynamic language setup failed: {}", e.getMessage());
}

When it happens

Trigger: `lang.getCommonWordsPath()` returns a path that does not exist after `Languages.addLanguage(name, code, new File(dictPath))` succeeds — typically because the dictionary file is malformed or the derived common-words location was never created.

Common situations: Custom dictionary file in the wrong format so the derived `hunspell/<code>/` common-words path is absent, wrong language code causing paths under a non-existent resource directory, or an incomplete LanguageTool installation.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• dictionary file does not exist or is not a file: ''
• code is supposed to be a 2 (or rarely 3) character code (unl
• must be set
• LanguageModel directory not found or is not a directory:
• Fasttext model path not valid (file doesn't exist or is a di

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