quarkusio/quarkus · error · TemplateException

Engine not set

Error message

Engine not set

What it means

FragmentNamespaceResolver.resolve() parses ids of the form templateId$fragmentId and looks up the template through an Engine reference. If the engine field has not been initialized (e.g. the resolver was used outside a managed Quarkus/Qute setup), it throws TemplateException("Engine not set").

Source

Thrown at independent-projects/qute/core/src/main/java/io/quarkus/qute/FragmentNamespaceResolver.java:58

        this.priority = priority;
    }

    @Override
    public void engineBuilt(Engine engine) {
        this.engine = engine;
    }

    @Override
    public CompletionStage<Object> resolve(EvalContext context) {
        String id = context.getName();
        Template template = null;
        int idx = id.lastIndexOf('$');
        if (idx != -1) {
            // the part before the last occurrence of a dollar sign is the template identifier
            String templateId = id.substring(0, idx);
            Engine e = engine;
            if (e == null) {
                throw new TemplateException("Engine not set");
            }
            template = e.getTemplate(templateId);
            if (template == null) {
                throw new TemplateException("Template not found: " + templateId);
            }
            // the part after the last occurrence of a dollar sign is the fragment identifier
            id = id.substring(idx + 1);
        } else {
            template = context.resolutionContext().getTemplate();
        }
        Fragment fragment = template.getFragment(id);
        if (fragment != null) {
            CompletableFuture<Object> ret = new CompletableFuture<>();
            if (!context.getParams().isEmpty()) {
                EvaluatedParams params = EvaluatedParams.evaluate(context);
                params.stage.whenComplete((r, t) -> {
                    if (t != null) {
                        ret.completeExceptionally(t);

View on GitHub (pinned to e1c734241f)

Solutions

1. Set the engine on the resolver (constructor/setter) before resolving fragment ids.
2. In plain Qute (non-Quarkus), use EngineBuilder to install the fragment namespace resolver with the engine instance.
3. In Quarkus, let the extension wire the resolver instead of instantiating it manually.

Example fix

// before
FragmentNamespaceResolver r = new FragmentNamespaceResolver();
// engine never set -> TemplateException
// after
Engine engine = Engine.builder().addNamespaceResolver(...).build();
FragmentNamespaceResolver r = new FragmentNamespaceResolver(engine); // engine wired

if (resolverEngine == null) {
    throw new IllegalStateException("Wire FragmentNamespaceResolver with an Engine before resolving");
}

boolean resolverReady(FragmentNamespaceResolver r) {
    return r != null; // ensure constructed via path that injects the engine
}

try {
    return resolver.resolve(ctx);
} catch (TemplateException ex) {
    if (ex.getMessage().contains("Engine not set")) {
        throw new IllegalStateException("Resolver misconfigured: engine missing", ex);
    }
    throw ex;
}

When it happens

Trigger: Resolving a {frag ...} / fragment namespace expression where the resolver's Engine reference was never injected or set — typically when the resolver is constructed manually in a plain Qute Engine setup or used before engine initialization.

Common situations: Unit tests constructing FragmentNamespaceResolver by hand without wiring the engine; using fragments outside the Quarkus Qute extension which normally injects the engine; engine closed or not yet started.

Related errors

• Template not found:
• Invalid template link [${templateLink}] - Expeting a link th
• Templates that are not backed by a file must provide extensi
• Literal must not be null
• Expression is not a literal:

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