quarkusio/quarkus · error · MessageBundleException

Message template for key [%s] is missing for default locale

Error message

Message template for key [%s] is missing for default locale [%s]

What it means

Every message key in a bundle must have a template for the bundle's default locale. When processing bundle methods/properties, if no message template is found for a key in the default locale, MessageBundleException is thrown at build time.

Source

Thrown at extensions/qute/deployment/src/main/java/io/quarkus/qute/deployment/MessageBundleProcessor.java:1140

                                            .append(enumConstantKey)
                                            .append("}");
                                    // For each constant we generate a method:
                                    // myEnum_CONSTANT(MyEnum val)
                                    // myEnum_$CONSTANT_1(MyEnum val)
                                    // myEnum_$CONSTANT$NEXT(MyEnum val)
                                    generateEnumConstantMessageMethod(cc, bundleName, locale, bundleInterface,
                                            defaultBundleInterface, enumConstantKey, keyMap, enumConstantTemplate,
                                            messageTemplateMethods);
                                }
                                generatedMessageTemplate.append("{/when}");
                                messageTemplate = generatedMessageTemplate.toString();
                                generatedTemplate = true;
                            }
                        }
                    }

                    if (messageTemplate == null) {
                        throw new MessageBundleException(
                                String.format("Message template for key [%s] is missing for default locale [%s]", key,
                                        bundle.getDefaultLocale()));
                    }

                    String templateId = null;
                    String defaultLocale = locale;
                    if (messageTemplate.contains("}")) {
                        // Qute is needed - at least one expression/section found
                        if (defaultBundleInterface != null) {
                            if (defaultLocale == null) {
                                AnnotationInstance localizedAnnotation = bundleInterface.declaredAnnotation(Names.LOCALIZED);
                                defaultLocale = localizedAnnotation.value().asString();
                            }
                            templateId = bundleName + "_" + defaultLocale + "_" + key;
                        } else {
                            templateId = bundleName + "_" + key;
                        }
                    }

View on GitHub (pinned to e1c734241f)

Solutions

1. Add the missing key/template to the default locale bundle file (e.g. src/main/resources/messages/messages.properties)
2. Or annotate the bundle interface method with @Message("template") to provide the default template inline
3. Verify the method name matches the key in the properties file exactly

Example fix

// before: only messages_de.properties has greeting=Hallo
// messages.properties
// after
greeting=Hello

// Ensure default locale file contains all keys
Properties def = new Properties();
def.load(getClass().getResourceAsStream("/messages/messages.properties"));
for (String key : requiredKeys) {
    if (!def.containsKey(key)) throw new IllegalStateException("Missing default-locale key: " + key);
}

When it happens

Trigger: A @MessageBundle interface declares a method (key) whose template is missing from the default-locale message file (or no @Message annotation provides the template), e.g. only non-default-locale .properties files define the key.

Common situations: Translating messages: adding keys to messages_de.properties but forgetting messages.properties; mismatch between method name and properties key; renamed method without updating properties file.

Related errors

• Locale of [%s] conflicts with the locale [%s] of the default
• Cannot register [%s] - a localized message bundle interface
• Enum constant message not found in bundle [%s] for key: %s
• Duplicate localized files with priority {priority} found: -
• Message bundle name [%s] declared on %s must be a valid name

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