languagetool-org/languagetool · error · BadRequestException

Invalid format for 'preferredVariants', expected a dash as i

Error message

Invalid format for 'preferredVariants', expected a dash as in 'en-GB': '{preferredVariant}'

What it means

LanguageTool's server rejects a 'preferredVariants' entry that lacks a dash separating language code from region/variant (e.g. 'en' instead of 'en-GB'). Preferred variants must be full language variants like 'en-GB' or 'de-DE'. The check runs in TextChecker before language resolution so malformed input fails fast with HTTP 400.

Source

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

                                          List<String> noopLangs, List<String> preferredLangs, boolean forcePreferredLanguages) {
    Language lang;
    String cleanText = languageIdentifier.cleanAndShortenText(text);
    DetectedLanguage detected = languageIdentifier.detectLanguage(cleanText, noopLangs, preferredLangs, forcePreferredLanguages);
    if (detected == null) {
      lang = parseLanguage(fallbackLanguage != null ? fallbackLanguage : "en");
    } else {
      lang = detected.getDetectedLanguage();
    }
    //String mode;
    //long t1 = System.nanoTime();
    //long t2 = System.nanoTime();
    //float runTime = (t2-t1)/1000.0f/1000.0f;
    //System.out.printf(Locale.ENGLISH, "detected " + detected + " using " + mode + " in %.2fms for %d chars\n", runTime, text.length());
    
    if (preferredVariants.size() > 0) {
      for (String preferredVariant : preferredVariants) {
        if (!preferredVariant.contains("-")) {
          throw new BadRequestException("Invalid format for 'preferredVariants', expected a dash as in 'en-GB': '" + preferredVariant + "'");
        }
        String preferredVariantLang = preferredVariant.split("-")[0];
        if (preferredVariantLang.equals(lang.getShortCode())) {
          lang = parseLanguage(preferredVariant);
          if (lang == null) {
            throw new BadRequestException("Invalid 'preferredVariants', no such language/variant found: '" + preferredVariant + "'");
          }
        }
      }
    } else {
      if (lang.getDefaultLanguageVariant() != null) {
        lang = lang.getDefaultLanguageVariant();
      }
    }
    return new DetectedLanguage(null, lang, detected != null ? detected.getDetectionConfidence() : 0f,
      detected != null ? detected.getDetectionSource() : null);
  }

View on GitHub (pinned to 2e990059ce)

Solutions

1. Include the variant part: use 'en-GB', 'en-US', 'de-DE' etc., not bare codes
2. Validate each comma-separated entry contains '-' before calling the API
3. If only a language is known, drop it from preferredVariants and rely on language=auto detection
4. Check the parameter spelling is preferredVariants (uppercase V) in v2 API

Example fix

// before
params.put("preferredVariants", "en,de-DE");
// after
params.put("preferredVariants", "en-US,de-DE");

function validatePreferredVariants(v) {
  const items = String(v).split(/,\s*/);
  if (items.some(i => !i.includes("-"))) throw new Error("preferredVariants entries need a dash, e.g. en-GB");
}

const isLangVariant = (s) => typeof s === 'string' && /^[a-z]{2,3}-[A-Za-z0-9]+$/.test(s);

When it happens

Trigger: POSTing to /v2/check with preferredVariants=en or preferredVariants=en,de (comma list containing a dash-less item); any entry not containing '-' throws.

Common situations: Clients pass a bare language code (from a UI language selector) instead of a full variant; code that splits user locale incorrectly; hand-built query strings assuming 'language' syntax works for preferredVariants.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Only either 'text' or 'markup' are supported in an object in
• 'text' cannot be used with 'interpretAs' (only 'markup' can)
• Only 'text' and 'markup' are supported in 'annotation' list:
• Invalid 'preferredVariants', no such language/variant found:
• You specified 'preferredVariants' but you didn't specify 'la

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