quarkusio/quarkus · error · java.lang.IllegalStateException

Bean not found for localized interface [{e.value}] and local

Error message

Bean not found for localized interface [{e.value}] and locale [{e.key}]

What it means

During namespace resolver setup, MessageBundles maps each localized bundle interface variant to a CDI bean selected with a @Localized qualifier. If the container has no bean for the interface + locale combination (unsatisfied dependency), setupNamespaceResolvers throws IllegalStateException('Bean not found for localized interface ... and locale ...').

Source

Thrown at extensions/qute/runtime/src/main/java/io/quarkus/qute/i18n/MessageBundles.java:118

    static void setupNamespaceResolvers(@Observes EngineBuilder builder, Instance<BundleContext> context) {
        if (!context.isResolvable()) {
            return;
        }
        // Avoid injecting "Instance<Object> instance" which prevents unused beans removal
        ArcContainer container = Arc.container();
        // For every bundle register a new resolver
        for (Entry<String, Map<String, Class<?>>> entry : context.get().getBundleInterfaces().entrySet()) {
            final String bundleName = entry.getKey();
            final Map<String, Resolver> interfaces = new HashMap<>();
            Resolver resolver = null;
            for (Entry<String, Class<?>> locEntry : entry.getValue().entrySet()) {
                if (locEntry.getKey().equals(DEFAULT_LOCALE)) {
                    resolver = (Resolver) container.select(locEntry.getValue(), Default.Literal.INSTANCE).get();
                    continue;
                }
                Instance<?> found = container.select(locEntry.getValue(), new Localized.Literal(locEntry.getKey()));
                if (found.isUnsatisfied()) {
                    throw new IllegalStateException(
                            Qute.fmt("Bean not found for localized interface [{e.value}] and locale [{e.key}]")
                                    .data("e", locEntry).render());
                }
                if (found.isAmbiguous()) {
                    throw new IllegalStateException(
                            Qute.fmt("Multiple beans found for localized interface [{e.value}] and locale [{e.key}]")
                                    .data("e", locEntry).render());
                }
                interfaces.put(locEntry.getKey(), (Resolver) found.get());
            }
            final Resolver defaultResolver = resolver;

            builder.addNamespaceResolver(new NamespaceResolver() {
                @Override
                public CompletionStage<Object> resolve(EvalContext context) {
                    Object locale = context.getAttribute(ATTRIBUTE_LOCALE);
                    if (locale == null) {
                        Object selectedVariant = context.getAttribute(TemplateInstance.SELECTED_VARIANT);

View on GitHub (pinned to e1c734241f)

Solutions

1. Add or restore the @Localized variant for the reported locale (bundle .properties file or @Localized bean)
2. Ensure the @Localized value matches exactly the locale key being looked up (e.g. 'de-DE' vs 'de')
3. Rebuild the app so bundle beans are generated for all declared locales
4. Align quarkus.locales config with the available bundle variants

Example fix

// before (missing fr variant, still registered in locales)
// after
@Localized("fr")
@MessageBundle
public interface AppMessagesFr { ... } // or add messages_fr.properties

// Build-time sanity check: every locale key must have a matching @Localized bean class
for (String locale : declaredLocales) {
    if (!localizedBundleClasses.containsKey(locale)) {
        throw new IllegalStateException("Missing @Localized variant for " + locale);
    }
}

When it happens

Trigger: A @MessageBundle interface declares localized variants but the corresponding @Localized bean for a specific locale is missing at runtime — typically when DEFAULT_LOCALE handling is bypassed and a non-default locale key has no registered bean.

Common situations: Locale-specific bundle files/beans removed or renamed while the locale map still references them; @Localized annotation value mismatch with the configured locale; build-time/generated bean registration skipped for that locale.

Related errors

• Unable to obtain a message bundle for interface [{ifacename}
• Locale of [%s] conflicts with the locale [%s] of the default
• Cannot register [%s] - a localized message bundle interface
• Not a message bundle interface:
• Multiple beans found for localized interface [{e.value}] and

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