{"record":{"id":"ea2bb476ed041e73","repo":"quarkusio/quarkus","slug":"startswith-match-the-path-templatepath-but-the","errorCode":null,"errorMessage":"<startsWith> match the path <templatePath> but the file suffix is not configured via the quarkus.qute.suffixes property","messagePattern":"<startsWith> match the path <templatePath> but the file suffix is not configured via the quarkus\\.qute\\.suffixes property","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":403,"sourceCode":"                                    fullPath, method.declaringClass().name(), method,\n                                    checkedTemplate));\n                }\n                if (!filePaths.contains(templatePath)\n                        && isNotLocatedByCustomTemplateLocator(locatorPatternsBuildItem.getLocationPatterns(),\n                                templatePath)) {\n                    List<String> startsWith = new ArrayList<>();\n                    for (String filePath : filePaths.getFilePaths()) {\n                        if (filePath.startsWith(templatePath)\n                                && filePath.charAt(templatePath.length()) == '.') {\n                            startsWith.add(filePath);\n                        }\n                    }\n                    if (startsWith.isEmpty()) {\n                        throw new TemplateException(\n                                \"No template matching the path \" + templatePath + \" could be found for: \"\n                                        + targetClass.name() + \".\" + method.name());\n                    } else {\n                        throw new TemplateException(\n                                startsWith + \" match the path \" + templatePath\n                                        + \" but the file suffix is not configured via the quarkus.qute.suffixes property\");\n                    }\n                }\n\n                Map<String, String> bindings = new HashMap<>();\n                List<Type> parameters = method.parameterTypes();\n                List<String> parameterNames = new ArrayList<>(parameters.size());\n                for (int i = 0; i < parameters.size(); i++) {\n                    Type type = parameters.get(i);\n                    String name = method.parameterName(i);\n                    if (name == null) {\n                        throw new TemplateException(\"Parameter names not recorded for \" + targetClass.name()\n                                + \": compile the class with -parameters\");\n                    }\n                    bindings.put(name, getCheckedTemplateParameterTypeName(type));\n                    parameterNames.add(name);\n                }","sourceCodeStart":385,"sourceCodeEnd":421,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/qute/deployment/src/main/java/io/quarkus/qute/deployment/QuteProcessor.java#L385-L421","documentation":"During Quarkus build, @CheckedTemplate processing validates that a template file exists for each checked template path. When files starting with the template path (same base name, different suffix, e.g. foo.md vs expected foo.html) are found but none has a configured suffix, Qute throws this TemplateException instead of a generic not-found error. It tells you the template exists but its suffix is not among the quarkus.qute.suffixes.","triggerScenarios":"A @CheckedTemplate (or @TemplateData-backed checked template) references path e.g. 'items/list'; the file items/list.qute.html (or .md, .txt) exists in src/main/resources/templates, but its suffix is not in quarkus.qute.suffixes (which defaults to ['html'] for base content types). collectCheckedTemplates in QuteProcessor scans template paths and finds only startsWith matches with unconfigured suffixes.","commonSituations":"Using non-HTML templates (txt, md, json) without adding their suffix to quarkus.qute.suffixes; moving templates to files with compound suffixes like .qute.html while expecting base-name matching; renaming template files after the default suffix config was narrowed.","solutions":["Add the actual file suffix to application.properties, e.g. quarkus.qute.suffixes=html,md,txt (or quarkus.qute.suffixes=html,qute.html as appropriate)","Rename the template file so its suffix matches a configured suffix, e.g. items/list.html","Set quarkus.qude.content-types or use the exact full path in @CheckedTemplate(location=\"items/list.qute.html\") so no suffix resolution is needed","Verify src/main/resources/templates contains the file under the exact path package-derived from the checked template interface"],"exampleFix":"// before: src/main/resources/templates/items/list.md, @CheckedTemplate interface Templates { TemplateInstance items$list(); }\n// application.properties has no qute suffix config -> build fails\n// after\n// application.properties:\n// quarkus.qute.suffixes=html,md","handlingStrategy":"validation","validationCode":"// before build: ensure suffix configured\n// application.properties\n// quarkus.qute.suffixes=html,md  (must include every suffix under templates/)\nList<Path> files = Files.walk(Path.of(\"src/main/resources/templates\"))\n    .filter(Files::isRegularFile).toList();\nSet<String> configured = Set.of(\"html\", \"md\");\nfor (Path f : files) {\n    String name = f.getFileName().toString();\n    String suffix = name.substring(name.indexOf('.') + 1);\n    if (!configured.contains(suffix)) throw new IllegalStateException(\"Suffix not configured: \" + f);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep quarkus.qute.suffixes in sync with actual template file extensions","Prefer .html for default config or explicitly list extra suffixes","Use full location (with suffix) in @CheckedTemplate when suffix is unusual","Add a build check or test scanning templates/ for unconfigured suffixes"],"tags":["qute","build-time","template-not-found","configuration"],"backgroundTag":"qute-template-suffix-not-configured","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}