languagetool-org/languagetool · error · IllegalArgumentException

'${langCode}' is not a language code known to LanguageTool.

Error message

'${langCode}' is not a language code known to LanguageTool. Supported language codes are: ${String.join(", ", getLangCodes())}. The list of languages is read from ${PROPERTIES_PATH} in the Java classpath. See https://dev.languagetool.org/java-api for details.

What it means

Languages.getLanguageForShortCode() looks up the given language code in the mapping loaded from language.properties on the classpath. If the code is unknown and not in the noopLanguageCodes list, it throws IllegalArgumentException listing all supported codes.

Source

Thrown at languagetool-core/src/main/java/org/languagetool/Languages.java:239

  /**
   * Get the Language object for the given language code.
   * @param langCode e.g. <code>en</code> or <code>en-US</code>
   * @param noopLanguageCodes list of languages that can be detected but that will not actually find any errors
   *                           (can be used so non-supported languages are not detected as some other language)
   * @throws IllegalArgumentException if the language is not supported or if the language code is invalid
   * @since 4.4
   */
  public static Language getLanguageForShortCode(String langCode, List<String> noopLanguageCodes) {
    Language language = getLanguageForShortCodeOrNull(langCode);
    if (language == null) {
      // e.g. 'fr-FR' requested (happens with LibreOffice 7.4):
      language = Languages.getLongCodeToLangMapping().get(langCode);
    }
    if (language == null) {
      if (noopLanguageCodes.contains(langCode)) {
        return NOOP_LANGUAGE;
      } else {
        throw new IllegalArgumentException("'" + langCode + "' is not a language code known to LanguageTool." +
                " Supported language codes are: " + String.join(", ", getLangCodes()) + ". The list of languages is read from " + PROPERTIES_PATH +
                " in the Java classpath. See https://dev.languagetool.org/java-api for details.");
      }
    }
    return language;
  }

  @NotNull
  private static List<String> getLangCodes() {
    List<String> codes = new ArrayList<>();
    for (Language realLanguage : getStaticAndDynamicLanguages()) {
      codes.add(realLanguage.getShortCodeWithCountryAndVariant());
    }
    Map<String, Language> longCodeToLang = getLongCodeToLangMapping();
    for (Map.Entry<String, Language> entry : longCodeToLang.entrySet()) {
      if (!codes.contains(entry.getKey())) {
        codes.add(entry.getKey());
      }

View on GitHub (pinned to 2e990059ce)

Solutions

1. Validate the code against Languages.getLangCodes() (or Languages.isLanguageSupported) before lookup
2. Fix the code spelling / use a supported variant code (e.g. 'en-US')
3. Upgrade or check the classpath so the correct language.properties is loaded

Example fix

// before
Language lang = Languages.getLanguageForShortCode(userInput); // throws
// after
if (Languages.isLanguageSupported(userInput)) {
  Language lang = Languages.getLanguageForShortCode(userInput);
}

if (!Languages.isLanguageSupported(code)) { throw new IllegalArgumentException("Unsupported language code: " + code + "; supported: " + Languages.getLangCodes()); }

try { Language lang = Languages.getLanguageForShortCode(code); } catch (IllegalArgumentException e) { lang = defaultLanguage; /* or return 400 to client */ }

When it happens

Trigger: Calling getLanguageForShortCode("xx") with a 2-3 letter code not present in language.properties and not a noop code (e.g. misspelled code like 'en-USX', removed language, or placeholder value).

Common situations: Passing user-supplied language codes from HTTP requests without validation; using a language code from an older LanguageTool version that was removed; confusing ISO 639-3 and 639-1 codes.

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

• Unknown mode: <mode>
• No IssueType found for name '" + name + "'. Valid values: "
• factor must be > 0: " + score
• WrongParameterNumberException
• You have to set the source language (as mother tongue) in bi

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