quarkusio/quarkus · error · IllegalArgumentException

Unable to resolve locale: ${value}

Error message

Unable to resolve locale: ${value}

What it means

LocaleConverter.convert() parses a configured quarkus.* locale string into a java.util.Locale. It normalizes '_' separators to '-' and uses Locale.forLanguageTag; if the resulting locale is not ROOT but has no language component, the value could not be resolved and this IllegalArgumentException is thrown. It indicates a malformed or meaningless locale setting in configuration.

Source

Thrown at core/runtime/src/main/java/io/quarkus/runtime/configuration/LocaleConverter.java:38

    public LocaleConverter() {
    }

    @Override
    public Locale convert(final String value) {
        final String localeValue = value.trim();

        if (localeValue.isEmpty()) {
            return null;
        }

        if ("all".equals(localeValue)) {
            return Locale.ROOT;
        }

        Locale locale = Locale.forLanguageTag(NORMALIZE_LOCALE_PATTERN.matcher(localeValue).replaceAll("-"));
        if (locale != Locale.ROOT && (locale.getLanguage() == null || locale.getLanguage().isEmpty())) {
            throw new IllegalArgumentException("Unable to resolve locale: " + value);
        }

        return locale;
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

1. Fix the quarkus.default-locale / quarkus.locales value to a valid BCP-47 language tag, e.g. 'en', 'en-US', 'fr-FR' (use '-' or '_' between subtags).
2. Use the literal value 'all' if you intend to accept all locales / the root locale.
3. Check the environment variable or property source feeding the value — an empty or mangled value (e.g. QUARKUS_DEFAULT_LOCALE="_") will trigger this.
4. Validate the tag with Locale.forLanguageTag().getLanguage() locally before adding it to configuration.

Example fix

// application.properties before
quarkus.default-locale=_US
// after
quarkus.default-locale=en-US

String v = configValue; // e.g. quarkus.default-locale
if (!"all".equals(v)) {
    Locale l = Locale.forLanguageTag(v.replace('_', '-'));
    if (l != Locale.ROOT && (l.getLanguage() == null || l.getLanguage().isEmpty())) {
        throw new IllegalArgumentException("Invalid locale config: " + v);
    }
}

boolean isValidLocale(String v) {
    if (v == null || "all".equals(v)) return true;
    Locale l = Locale.forLanguageTag(v.replace('_', '-'));
    return l == Locale.ROOT || !l.getLanguage().isEmpty();
}

When it happens

Trigger: Setting quarkus.default-locale (or quarkus.locales) to a string like '_FR', '---', or another value whose language tag normalizes to something with an empty language but is not the literal "all" (which maps to Locale.ROOT).

Common situations: Typo in locale config (e.g. quarkus.default-locale="_US" or "123"), environment-variable interpolation producing an empty language prefix, copying an underscore format where the language part got dropped, or platform-dependent forLanguageTag silently returning a locale without a language.

Related errors

• Unknown JAR package type '${value}'
• Unsupported compressor '
• proxyHost must not be null
• Invalid port number
• Parameter type should be provided.

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/24ea1dcb526e92f4. Report an issue: GitHub.