quarkusio/quarkus · error · io.quarkus.qute.TemplateException

Fragment [<fragmentId>] not defined in template <templateId>

Error message

Fragment [<fragmentId>] not defined in template <templateId>

What it means

Thrown by Qute's analyzeTemplates build step when a type-safe fragment declared via a checked template (@CheckedTemplate fragment or checkTemplateFragment) cannot be found in the compiled template. Qute validates every checked fragment id against the fragments actually present in the template file (e.g. {@#myFragment}...{/}) and fails the build if the id does not resolve.

Source

Thrown at extensions/qute/deployment/src/main/java/io/quarkus/qute/deployment/QuteProcessor.java:840

            });
        }

        Engine dummyEngine = builder.build();
        List<CheckedTemplateBuildItem> checkedFragments = checkedTemplates.stream().filter(CheckedTemplateBuildItem::isFragment)
                .collect(Collectors.toList());

        for (TemplatePathBuildItem path : effectiveTemplatePaths.getTemplatePaths()) {
            Template template = dummyEngine.getTemplate(path.getPath());
            if (template != null) {
                String templateIdWithoutSuffix = templatePathWithoutSuffix(template.getId(), config);

                if (!checkedFragments.isEmpty()) {
                    for (CheckedTemplateBuildItem checkedFragment : checkedFragments) {
                        if (checkedFragment.templateId.equals(templateIdWithoutSuffix)) {
                            // Template matches a type-safe fragment
                            Template.Fragment fragment = template.getFragment(checkedFragment.fragmentId);
                            if (fragment == null) {
                                throw new TemplateException(
                                        "Fragment [" + checkedFragment.fragmentId + "] not defined in template "
                                                + template.getId());
                            }
                            checkedFragmentValidations
                                    .produce(new CheckedFragmentValidationBuildItem(template.getGeneratedId(),
                                            fragment.getExpressions(), checkedFragment));
                        }
                    }
                }

                analysis.add(new TemplateAnalysis(null, template, path.getPath()));
            }
        }

        // Message bundle templates
        for (MessageBundleMethodBuildItem messageBundleMethod : messageBundleMethods) {
            Template template = dummyEngine.parse(messageBundleMethod.getTemplate(), null, messageBundleMethod.getTemplateId());
            analysis.add(new TemplateAnalysis(messageBundleMethod.getTemplateId(), template,

View on GitHub (pinned to e1c734241f)

Solutions

1. Add the missing fragment to the template: wrap the relevant markup in {@#<fragmentId>} ... {/<fragmentId>}
2. Fix the fragment id: rename the Java Template.Fragment field (and the surrounding checked template class/package path) to match the fragment id defined in the template file
3. Remove the stale checked fragment field if the fragment is no longer needed
4. Verify the template file actually resolves under the id derived from the checked template class/package (suffix and base path configuration)

Example fix

// before
@CheckedTemplate
class ItemTemplates {
    public static final Template.Fragment details = Template.fragment(); // no 'details' fragment in template
}

<!-- templates/ItemTemplates/item.html has only -->
<div>...</div>

// after
<!-- templates/ItemTemplates/item.html -->
<div>
  {@#details}
  <span>{item.name}</span>
  {/details}
</div>

// Before build: ensure every checked fragment id exists in the template
String fragmentId = "details";
String templateBody = Files.readString(Path.of("src/main/resources/templates/ItemTemplates/item.html"));
if (!templateBody.contains("{#" + fragmentId + "}")) {
    throw new IllegalStateException("Fragment " + fragmentId + " missing from template");
}

When it happens

Trigger: A @CheckedTemplate nested class declares a static Template.Fragment field whose name matches no fragment defined in the template file; the fragment tag was renamed or removed from the .html file while the Java field still references the old id; the template resolved by the checked template id exists but was authored without the fragment block.

Common situations: Renaming a section in a Qute template during refactoring without updating the corresponding checked fragment field; typo between the Java field name and the fragment id; moving the fragment into another template file so the ids no longer line up.

Related errors

• No template extension methods declared on <class>; a templat
• Type ${className} must be annotated with @Embeddable, becaus
• No suitable template variant found
• No template variant 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/3c3a547c10f0292f. Report an issue: GitHub.