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

<startsWith> match the path <templatePath> but the file suff

Error message

<startsWith> match the path <templatePath> but the file suffix is not configured via the quarkus.qute.suffixes property

What it means

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.

Source

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

                                    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");
                    }
                    bindings.put(name, getCheckedTemplateParameterTypeName(type));
                    parameterNames.add(name);
                }

View on GitHub (pinned to e1c734241f)

Solutions

1. 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)
2. Rename the template file so its suffix matches a configured suffix, e.g. items/list.html
3. Set quarkus.qude.content-types or use the exact full path in @CheckedTemplate(location="items/list.qute.html") so no suffix resolution is needed
4. Verify src/main/resources/templates contains the file under the exact path package-derived from the checked template interface

Example fix

// before: src/main/resources/templates/items/list.md, @CheckedTemplate interface Templates { TemplateInstance items$list(); }
// application.properties has no qute suffix config -> build fails
// after
// application.properties:
// quarkus.qute.suffixes=html,md

// before build: ensure suffix configured
// application.properties
// quarkus.qute.suffixes=html,md  (must include every suffix under templates/)
List<Path> files = Files.walk(Path.of("src/main/resources/templates"))
    .filter(Files::isRegularFile).toList();
Set<String> configured = Set.of("html", "md");
for (Path f : files) {
    String name = f.getFileName().toString();
    String suffix = name.substring(name.indexOf('.') + 1);
    if (!configured.contains(suffix)) throw new IllegalStateException("Suffix not configured: " + f);
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• No template matching the path <templatePath> could be found
• The configuration ${clazz} is missing the @ConfigRoot annota
• Unsupported value: ${value}
• Invalid configuration value set for 'quarkus.arc.remove-unus
• Flyway migration location may not be null.

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