languagetool-org/languagetool · error · BadRequestException

You specified altLanguage '{langCode}', but for this languag

Error message

You specified altLanguage '{langCode}', but for this language you need to specify a variant, e.g. 'en-GB' instead of just 'en'

What it means

Some languages in LanguageTool exist only as variants (e.g. English en-GB/en-US). When an altLanguages entry names such a language without an explicit variant, checkText rejects the request with BadRequestException because the alt language cannot be instantiated unambiguously.

Source

Thrown at languagetool-server/src/main/java/org/languagetool/server/TextChecker.java:540

    Integer count = languageCheckCounts.get(lang.getShortCodeWithCountryAndVariant());
    if (count == null) {
      count = 1;
    } else {
      count++;
    }
    //print("Starting check: " + aText.getPlainText().length() + " chars, #" + count);
    String motherTongueParam = params.get("motherTongue");
    Language motherTongue = motherTongueParam != null ? parseLanguage(motherTongueParam) : null;
    boolean useEnabledOnly = "yes".equals(params.get("enabledOnly")) || "true".equals(params.get("enabledOnly"));
    List<Language> altLanguages = new ArrayList<>();
    if (params.get("altLanguages") != null) {
      String[] altLangParams = COMMA_WHITESPACE_PATTERN.split(params.get("altLanguages"));
      for (String langCode : altLangParams) {
        Language altLang = parseLanguage(langCode);
        altLanguages.add(altLang);
        if (altLang.hasVariant() && !altLang.isVariant()) {
          ServerMetricsCollector.getInstance().logRequestError(ServerMetricsCollector.RequestErrorType.INVALID_REQUEST);
          throw new BadRequestException("You specified altLanguage '" + langCode + "', but for this language you need to specify a variant, e.g. 'en-GB' instead of just 'en'");
        }
      }
    }
    List<String> enabledRules = getEnabledRuleIds(params);
    List<String> disabledRules = getDisabledRuleIds(params);
    List<CategoryId> enabledCategories = getCategoryIds("enabledCategories", params);
    List<CategoryId> disabledCategories = getCategoryIds("disabledCategories", params);


    if (shouldRunRestrictedRulesTest(params, agent, lang, abTest)) {
      log.info("Running test with restricted rules for user: {}, language: {}, client: {}",
        params.getOrDefault("username", ""), lang.getShortCodeWithCountryAndVariant(), agent);
      useEnabledOnly = true;
      enabledRules = onlyTestRules;
      // need to clear these settings, leads to conflict with useEnabledOnly otherwise
      disabledRules = Collections.emptyList();
      disabledCategories = Collections.emptyList();
    }

View on GitHub (pinned to 2e990059ce)

Solutions

1. Replace the bare code with a specific variant, e.g. altLanguages=en-GB instead of en
2. List each needed variant explicitly (altLanguages=en-US,en-GB,pt-BR)
3. Check Languages.getLanguageForShortCode to see which codes require a variant before building the request

Example fix

// before
curl -d text=... -d language=de-DE -d altLanguages=en http://server/v2/check
// after
curl -d text=... -d language=de-DE -d altLanguages=en-GB http://server/v2/check

const VARIANT_ONLY = ['en','de','pt','ca','nl']; // languages requiring variants
for (const code of (params.altLanguages || '').split(',')) {
  if (VARIANT_ONLY.includes(code.trim())) {
    throw new Error(`altLanguage '${code}' needs a variant, e.g. ${code}-GB`);
  }
}

function isFullVariant(code) {
  return typeof code === 'string' && /^[a-z]{2,3}-[A-Za-z]{2,4}$/.test(code.trim());
}

When it happens

Trigger: Sending altLanguages=en (or altLanguages=pt) where the parsed Language has hasVariant()==true but isVariant()==false — i.e. a bare short code for a variant-only language — in the /v2/check request.

Common situations: Users writing altLanguages=en assuming it covers all English; while the main 'language' parameter accepts bare codes for some setups, altLanguages demands fully specified variants; older client examples predate stricter validation.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• You can specify 'noopLanguages' only when also using 'langua
• You must specify enabled rules or categories when using enab
• {e.getMessage()} (invalid language code passed to Languages.
• You cannot specify disabled rules or categories using enable
• Missing 'text' or 'data' parameter

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