quarkusio/quarkus · error · java.lang.IllegalStateException

Unable to preload message template:

Error message

Unable to preload message template: 

What it means

MessageBundles.preloadMessageTemplates eagerly resolves each message bundle key to a compiled Qute template at startup. When the engine has no template registered under a bundle's key, it means the annotated @MessageBundle interface's generated template files are missing from the deployment, so startup fails fast instead of failing lazily at first use.

Source

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

                    return localeResolver != null ? localeResolver.resolve(context) : defaultResolver.resolve(context);
                }

                @Override
                public String getNamespace() {
                    return bundleName;
                }
            });
        }
    }

    static void preloadMessageTemplates(@Observes Engine engine, Instance<BundleContext> context) {
        if (!context.isResolvable()) {
            return;
        }
        for (String key : context.get().getMessageTemplates().keySet()) {
            Template messageTemplate = engine.getTemplate(key);
            if (messageTemplate == null) {
                throw new IllegalStateException("Unable to preload message template: " + key);
            }
        }
    }

    public static Template getTemplate(String id) {
        return Arc.container().instance(Engine.class).get().getTemplate(id);
    }

}

View on GitHub (pinned to e1c734241f)

Solutions

1. Add or restore the missing template file matching the reported key under src/main/resources/templates (e.g. templates/msg/app.properties or the localized template).
2. Check the bundle's @Location and name match the directory/files actually present in resources.
3. Ensure your build does not exclude template resources (maven resource filtering/includes).
4. Disable eager loading with quarkus.qute.i18n.preload=false if preloading is not needed.

Example fix

// before: bundle AppMessages in templates/msg but file missing
// after:
// src/main/resources/templates/msg/app.properties
// hello=Hello {name}

Path tpl = Path.of("src/main/resources/templates", bundleLocation);
if (!Files.exists(tpl)) throw new IllegalStateException("Missing bundle template: " + tpl);

try { bundleUsage(); } catch (IllegalStateException e) { if (e.getMessage().startsWith("Unable to preload message template")) { /* restore template or disable preload */ } else throw e; }

When it happens

Trigger: Calling preloadMessageTemplates (done automatically at startup when quarkus.qute.i18n.preload=true or for default bundles) while the template file corresponding to a message key (e.g. msg/index.html under the bundle's directory) does not exist in src/main/resources/templates.

Common situations: Renaming a message bundle @Location or bundle name without renaming the template directory; deleting or moving .html/.txt template files; build resource filtering excluding templates; typos between the bundle name and the templates directory name.

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
• Message template for key [%s] is missing for default locale
• Duplicate localized files with priority {priority} found: -

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