quarkusio/quarkus · error · TemplateException

Template not found:

Error message

Template not found: 

What it means

FragmentNamespaceResolver.resolve() splits the id into templateId$fragmentId and calls engine.getTemplate(templateId). It throws TemplateException("Template not found: <id>") when no template with that identifier is loaded by the engine.

Source

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

    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);
                    } else {
                        Map<String, Object> args = new HashMap<>();
                        for (int i = 0; i < context.getParams().size(); i++) {
                            try {

View on GitHub (pinned to e1c734241f)

Solutions

1. Verify the template id matches the path under src/main/resources/templates exactly (case-sensitive).
2. Inject the template via @Location or load it once so the engine has it registered.
3. Check that the file is included in the native image resources if running native.
4. Print/inspect available template ids to confirm the expected id exists.

Example fix

// before
@Inject
Template missing; // never matched -> Template not found: detail$item
// {frag detail$item}
// after
@Inject
@Location("detail")
Template detail; // matches id 'detail' used in fragment reference detail$item

Template t = engine.getTemplate("detail");
if (t == null) {
    throw new IllegalStateException("Template 'detail' not on classpath under templates/");
}

boolean templateExists(Engine e, String id) {
    return e.getTemplate(id) != null;
}

try {
    return resolver.resolve(ctx);
} catch (TemplateException ex) {
    if (ex.getMessage().startsWith("Template not found")) {
        LOGGER.error("Check templates dir and fragment id: {}", ex.getMessage());
    }
    throw ex;
}

When it happens

Trigger: Referencing a fragment like {#frag} from an id such as 'myTemplate$myFragment' where 'myTemplate' was never loaded, is misspelled, or was not included in the build (not in templates dir / not registered).

Common situations: Typo in the template id; template not placed under src/main/resources/templates; fragment id uses the wrong path prefix; in tests the template was never injected or loaded; native build excluded the template resource.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Engine not set
• Invalid template link [${templateLink}] - Expeting a link th
• <startsWith> match the path <templatePath> but the file suff
• No template matching the path <templatePath> could be found
• Templates that are not backed by a file must provide extensi

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