{"record":{"id":"24ea1dcb526e92f4","repo":"quarkusio/quarkus","slug":"unable-to-resolve-locale-value","errorCode":null,"errorMessage":"Unable to resolve locale: ${value}","messagePattern":"Unable to resolve locale: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"core/runtime/src/main/java/io/quarkus/runtime/configuration/LocaleConverter.java","lineNumber":38,"sourceCode":"\n    public LocaleConverter() {\n    }\n\n    @Override\n    public Locale convert(final String value) {\n        final String localeValue = value.trim();\n\n        if (localeValue.isEmpty()) {\n            return null;\n        }\n\n        if (\"all\".equals(localeValue)) {\n            return Locale.ROOT;\n        }\n\n        Locale locale = Locale.forLanguageTag(NORMALIZE_LOCALE_PATTERN.matcher(localeValue).replaceAll(\"-\"));\n        if (locale != Locale.ROOT && (locale.getLanguage() == null || locale.getLanguage().isEmpty())) {\n            throw new IllegalArgumentException(\"Unable to resolve locale: \" + value);\n        }\n\n        return locale;\n    }\n}\n","sourceCodeStart":20,"sourceCodeEnd":44,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/core/runtime/src/main/java/io/quarkus/runtime/configuration/LocaleConverter.java#L20-L44","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["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).","Use the literal value 'all' if you intend to accept all locales / the root locale.","Check the environment variable or property source feeding the value — an empty or mangled value (e.g. QUARKUS_DEFAULT_LOCALE=\"_\") will trigger this.","Validate the tag with Locale.forLanguageTag().getLanguage() locally before adding it to configuration."],"exampleFix":"// application.properties before\nquarkus.default-locale=_US\n// after\nquarkus.default-locale=en-US","handlingStrategy":"validation","validationCode":"String v = configValue; // e.g. quarkus.default-locale\nif (!\"all\".equals(v)) {\n    Locale l = Locale.forLanguageTag(v.replace('_', '-'));\n    if (l != Locale.ROOT && (l.getLanguage() == null || l.getLanguage().isEmpty())) {\n        throw new IllegalArgumentException(\"Invalid locale config: \" + v);\n    }\n}","typeGuard":"boolean isValidLocale(String v) {\n    if (v == null || \"all\".equals(v)) return true;\n    Locale l = Locale.forLanguageTag(v.replace('_', '-'));\n    return l == Locale.ROOT || !l.getLanguage().isEmpty();\n}","tryCatchPattern":null,"preventionTips":["Always specify a language component in locale config: 'en-US', not '_US'.","Use 'all' explicitly when the root locale is intended.","Check env vars/property sources feeding quarkus.default-locale and quarkus.locales for empty or malformed values.","Smoke-test the application with locale config set before shipping to production."],"tags":["configuration","locale","illegal-argument"],"backgroundTag":"invalid-locale-config","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}