{"record":{"id":"3c3a547c10f0292f","repo":"quarkusio/quarkus","slug":"fragment-fragmentid-not-defined-in-template-t","errorCode":null,"errorMessage":"Fragment [<fragmentId>] not defined in template <templateId>","messagePattern":"Fragment \\[<fragmentId>\\] not defined in template <templateId>","errorType":"exception","errorClass":"io.quarkus.qute.TemplateException","httpStatus":null,"severity":"error","filePath":"extensions/qute/deployment/src/main/java/io/quarkus/qute/deployment/QuteProcessor.java","lineNumber":840,"sourceCode":"            });\n        }\n\n        Engine dummyEngine = builder.build();\n        List<CheckedTemplateBuildItem> checkedFragments = checkedTemplates.stream().filter(CheckedTemplateBuildItem::isFragment)\n                .collect(Collectors.toList());\n\n        for (TemplatePathBuildItem path : effectiveTemplatePaths.getTemplatePaths()) {\n            Template template = dummyEngine.getTemplate(path.getPath());\n            if (template != null) {\n                String templateIdWithoutSuffix = templatePathWithoutSuffix(template.getId(), config);\n\n                if (!checkedFragments.isEmpty()) {\n                    for (CheckedTemplateBuildItem checkedFragment : checkedFragments) {\n                        if (checkedFragment.templateId.equals(templateIdWithoutSuffix)) {\n                            // Template matches a type-safe fragment\n                            Template.Fragment fragment = template.getFragment(checkedFragment.fragmentId);\n                            if (fragment == null) {\n                                throw new TemplateException(\n                                        \"Fragment [\" + checkedFragment.fragmentId + \"] not defined in template \"\n                                                + template.getId());\n                            }\n                            checkedFragmentValidations\n                                    .produce(new CheckedFragmentValidationBuildItem(template.getGeneratedId(),\n                                            fragment.getExpressions(), checkedFragment));\n                        }\n                    }\n                }\n\n                analysis.add(new TemplateAnalysis(null, template, path.getPath()));\n            }\n        }\n\n        // Message bundle templates\n        for (MessageBundleMethodBuildItem messageBundleMethod : messageBundleMethods) {\n            Template template = dummyEngine.parse(messageBundleMethod.getTemplate(), null, messageBundleMethod.getTemplateId());\n            analysis.add(new TemplateAnalysis(messageBundleMethod.getTemplateId(), template,","sourceCodeStart":822,"sourceCodeEnd":858,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/qute/deployment/src/main/java/io/quarkus/qute/deployment/QuteProcessor.java#L822-L858","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Add the missing fragment to the template: wrap the relevant markup in {@#<fragmentId>} ... {/<fragmentId>}","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","Remove the stale checked fragment field if the fragment is no longer needed","Verify the template file actually resolves under the id derived from the checked template class/package (suffix and base path configuration)"],"exampleFix":"// before\n@CheckedTemplate\nclass ItemTemplates {\n    public static final Template.Fragment details = Template.fragment(); // no 'details' fragment in template\n}\n\n<!-- templates/ItemTemplates/item.html has only -->\n<div>...</div>\n\n// after\n<!-- templates/ItemTemplates/item.html -->\n<div>\n  {@#details}\n  <span>{item.name}</span>\n  {/details}\n</div>","handlingStrategy":"validation","validationCode":"// Before build: ensure every checked fragment id exists in the template\nString fragmentId = \"details\";\nString templateBody = Files.readString(Path.of(\"src/main/resources/templates/ItemTemplates/item.html\"));\nif (!templateBody.contains(\"{#\" + fragmentId + \"}\")) {\n    throw new IllegalStateException(\"Fragment \" + fragmentId + \" missing from template\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always define fragments with {@#id}...{/id} blocks before declaring checked fragment fields","Rename template fragments and Java fields together in one refactoring commit","Keep checked template classes in packages that mirror the template directory structure","Run mvn compile early after template edits to catch id mismatches"],"tags":["quarkus","qute","build-time-validation","template-fragment"],"backgroundTag":"template-fragment-not-defined","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}