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: <recordClass>

What it means

Qute validates at build time that every checked template path corresponds to an existing template file under src/main/resources/templates (or a configured location). When no file path starts with the derived templatePath, collectCheckedTemplates throws this TemplateException naming the class (e.g. a record class used as a template record).

Source

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

                if (checkedTemplate != null) {
                    throw new TemplateException(
                            String.format(
                                    "Multiple checked templates exist for the template path %s:\n\t- %s\n\t- %s",
                                    fullPath, recordClass.name(), 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: "
                                        + recordClass.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 = canonicalConstructor.parameterTypes();
                for (int i = 0; i < parameters.size(); i++) {
                    Type type = parameters.get(i);
                    String name = canonicalConstructor.parameterName(i);
                    if (name == null) {
                        throw new TemplateException("Parameter names not recorded for " + recordClass.name()
                                + ": compile the class with -parameters");
                    }

View on GitHub (pinned to e1c734241f)

Solutions

1. Create/rename the template file at the exact expected location, e.g. src/main/resources/templates/items/list.html
2. Add @CheckedTemplate(basePath=...) or location=... to point at the real file
3. Check the file lives in src/main/resources/templates of the same module/application, not tests or a dependency
4. If templates come from a custom TemplateLocator, ensure the build-time validation is satisfied (file present) or the path patterns allow it

Example fix

// before: record item(record String name) {} in io.acme; templates dir has templates/Item.html
// after: move file to src/main/resources/templates/io/acme/item.html
// or: @CheckedTemplate(basePath=".") record item(...) {}

// check the expected file exists before build
String pkg = Templates.class.getPackageName().replace('.', '/');
Path expected = Path.of("src/main/resources/templates", pkg, "item.html");
if (!Files.exists(expected)) {
    throw new IllegalStateException("Missing checked template: " + expected);
}

When it happens

Trigger: A template record class (or @CheckedTemplate) declares a template path 'items/list' but no file starting with 'items/list.' exists in the templates root; the derived path from package + class name does not match the actual directory layout; the file was deleted/renamed or is in the wrong resources root.

Common situations: Package-to-directory mismatch (class io.acme.ItemTemplates expects templates/io/acme/...); typo in file name; template placed in src/test/resources or another module; missing quarkus.qute.template-path-prefix style configuration for custom locations; using custom template locators but forgetting basePath config.

Related errors

• <startsWith> match the path <templatePath> but the file suff
• Message bundle name [%s] declared on %s must be a valid name
• Message bundle interface name conflict - [%s] is used for bo
• @MessageBundle must be declared on an interface: {bundleClas
• Parameter names not recorded for <targetClass>: compile the

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