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

Multiple checked templates exist for the template path %s:

Error message

Multiple checked templates exist for the template path %s:
	- %s: %s
	- %s

What it means

Each template path may be bound to exactly one @CheckedTemplate method. When two methods (possibly in different classes) map to the same full template path (including fragment id), Qute cannot decide which one owns it and throws TemplateException listing both.

Source

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

                if (method.returnType().kind() != Type.Kind.CLASS) {
                    throw new TemplateException("Incompatible checked template return type: " + method.returnType()
                            + " only " + supportedAdaptors);
                }
                DotName returnTypeName = method.returnType().asClassType().name();
                CheckedTemplateAdapter adaptor = null;
                // if it's not the default template instance, try to find an adapter
                if (!returnTypeName.equals(Names.TEMPLATE_INSTANCE)) {
                    adaptor = adaptors.get(returnTypeName);
                    if (adaptor == null)
                        throw new TemplateException("Incompatible checked template return type: " + method.returnType()
                                + " only " + supportedAdaptors);
                }
                String fragmentId = getCheckedFragmentId(method, annotation);
                String templatePath = getCheckedTemplatePath(index.getIndex(), annotation, fragmentId, targetClass, method);
                String fullPath = templatePath + (fragmentId != null ? "$" + fragmentId : "");
                AnnotationTarget checkedTemplate = checkedTemplates.putIfAbsent(fullPath, method);
                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: "

View on GitHub (pinned to e1c734241f)

Solutions

1. Rename one of the conflicting methods or move it so paths differ
2. Use a distinct basePath in the @CheckedTemplate annotation of one class
3. Delete the duplicate method if it is redundant

Example fix

// before
class A { @CheckedTemplate(basePath="item") static native TemplateInstance page(); }
class B { @CheckedTemplate(basePath="item") static native TemplateInstance page(); }
// after
class B { @CheckedTemplate(basePath="item2") static native TemplateInstance page(); }

// Detect duplicate template paths in a test
Set<String> seen = new HashSet<>();
for (Class<?> c : List.of(A.Templates.class, B.Templates.class)) {
    for (Method m : c.getDeclaredMethods()) {
        if (m.isAnnotationPresent(CheckedTemplate.class)
            && !seen.add(c.getSimpleName() + "." + m.getName()))
            throw new IllegalStateException("Duplicate template binding: " + m);
    }
}

When it happens

Trigger: Two @CheckedTemplate methods resolving to the same template path — e.g. nested Templates classes with identical basePath, or same method name in nested/inner template classes, or duplicate fragment ids.

Common situations: Inner static Templates classes in different classes sharing the same @CheckedTemplate basePath; copying a Templates class; method renames colliding with existing keys; same template accessed via two checked APIs.

Related errors

• Cannot register [%s] - a localized message bundle interface
• Incompatible checked template return type: {returnType} only
• Incompatible checked template return type: <returnType> only
• No template matching the path <templatePath> could be found
• Multiple checked templates exist for the template path %s:

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