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

No template matching the path <templatePath> could be found

Error message

No template matching the path <templatePath> could be found for: <targetClass>.<method>

What it means

After resolving a @CheckedTemplate method's expected template path, Qute verifies a template file with that path exists among indexed templates. If no file starting with that path (with a configured suffix) exists, TemplateException is thrown naming the path and the declaring class/method.

Source

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

                if (checkedTemplate != null) {
                    throw new TemplateException(
                            String.format(
                                    "Multiple checked templates exist for the template path %s:\n\t- %s: %s\n\t- %s",
                                    fullPath, method.declaringClass().name(), method,
                                    checkedTemplate));
                }
                if (!filePaths.contains(templatePath)
                        && isNotLocatedByCustomTemplateLocator(locatorPatternsBuildItem.getLocationPatterns(),
                                templatePath)) {
                    List<String> startsWith = new ArrayList<>();
                    for (String filePath : filePaths.getFilePaths()) {
                        if (filePath.startsWith(templatePath)
                                && filePath.charAt(templatePath.length()) == '.') {
                            startsWith.add(filePath);
                        }
                    }
                    if (startsWith.isEmpty()) {
                        throw new TemplateException(
                                "No template matching the path " + templatePath + " could be found for: "
                                        + targetClass.name() + "." + method.name());
                    } else {
                        throw new TemplateException(
                                startsWith + " match the path " + templatePath
                                        + " but the file suffix is not configured via the quarkus.qute.suffixes property");
                    }
                }

                Map<String, String> bindings = new HashMap<>();
                List<Type> parameters = method.parameterTypes();
                List<String> parameterNames = new ArrayList<>(parameters.size());
                for (int i = 0; i < parameters.size(); i++) {
                    Type type = parameters.get(i);
                    String name = method.parameterName(i);
                    if (name == null) {
                        throw new TemplateException("Parameter names not recorded for " + targetClass.name()
                                + ": compile the class with -parameters");

View on GitHub (pinned to e1c734241f)

Solutions

1. Create the template file at the exact path reported (under src/main/resources/templates)
2. Fix the basePath/@CheckedTemplate annotation or method name to match the actual file
3. Verify file name case and extension; if using a non-default extension, add it to quarkus.qute.suffixes

Example fix

// before: Templates.page() with no file
// after
$ touch src/main/resources/templates/page.html

// Verify template resource exists before app start
String path = "templates/page.html";
if (getClass().getClassLoader().getResource(path) == null)
    throw new IllegalStateException("Template missing: " + path);

When it happens

Trigger: A @CheckedTemplate method refers to templates/hello.txt etc. but no template file at that path exists in src/main/resources/templates; path typo, wrong basePath, or file never created.

Common situations: Renaming/moving template files without updating the Templates class; case-sensitive filesystems where Hello.html ≠ hello.html; template placed in the wrong directory; missing suffix configuration for unusual extensions.

Related errors

• Unable to read the template content from path: <path>
• Incompatible checked template return type: {returnType} only
• Incompatible checked template return type: <returnType> only
• Multiple checked templates exist for the template path %s:
• Unable to render config roots for top level prefix: ${topLev

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