{"record":{"id":"be0de119f1dfc861","repo":"quarkusio/quarkus","slug":"incompatible-checked-template-return-type-return-be0de1","errorCode":null,"errorMessage":"Incompatible checked template return type: <returnType> only <supportedAdaptors>","messagePattern":"Incompatible checked template return type: <returnType> only <supportedAdaptors>","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":374,"sourceCode":"            NativeCheckedTemplateEnhancer enhancer = new NativeCheckedTemplateEnhancer();\n            for (MethodInfo method : targetClass.methods()) {\n                // only keep native static methods\n                if (!Modifier.isStatic(method.flags())\n                        || !Modifier.isNative(method.flags())) {\n                    continue;\n                }\n                // check its return type\n                if (method.returnType().kind() != Type.Kind.CLASS) {\n                    throw new TemplateException(\"Incompatible checked template return type: \" + method.returnType()\n                            + \" only \" + supportedAdaptors);\n                }\n                DotName returnTypeName = method.returnType().asClassType().name();\n                CheckedTemplateAdapter adaptor = null;\n                // if it's not the default template instance, try to find an adapter\n                if (!returnTypeName.equals(Names.TEMPLATE_INSTANCE)) {\n                    adaptor = adaptors.get(returnTypeName);\n                    if (adaptor == null)\n                        throw new TemplateException(\"Incompatible checked template return type: \" + method.returnType()\n                                + \" only \" + supportedAdaptors);\n                }\n                String fragmentId = getCheckedFragmentId(method, annotation);\n                String templatePath = getCheckedTemplatePath(index.getIndex(), annotation, fragmentId, targetClass, method);\n                String fullPath = templatePath + (fragmentId != null ? \"$\" + fragmentId : \"\");\n                AnnotationTarget checkedTemplate = checkedTemplates.putIfAbsent(fullPath, method);\n                if (checkedTemplate != null) {\n                    throw new TemplateException(\n                            String.format(\n                                    \"Multiple checked templates exist for the template path %s:\\n\\t- %s: %s\\n\\t- %s\",\n                                    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()) {","sourceCodeStart":356,"sourceCodeEnd":392,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/qute/deployment/src/main/java/io/quarkus/qute/deployment/QuteProcessor.java#L356-L392","documentation":"Same family as error 1576 but hit when the return type is a class type not equal to TemplateInstance and no CheckedTemplateAdapter is registered for that exact type name. The build fails listing only the supported adaptor types.","triggerScenarios":"A @CheckedTemplate static native method returns e.g. Uni<TemplateInstance>, String, or a custom DTO, and no CheckedTemplateAdapter is registered for that returned type name.","commonSituations":"Mistakenly declaring the raw entity type instead of TemplateInstance; copying patterns from REST where Uni<Response> works; missing qute adaptation extension for a reactive type.","solutions":["Return TemplateInstance from the @CheckedTemplate method","If returning a custom wrapper, implement and register a CheckedTemplateAdapter","Check that the intended return type matches one listed in the error's supportedAdaptors"],"exampleFix":"// before\n@CheckedTemplate\nstatic native String hello();\n// after\n@CheckedTemplate\nstatic native TemplateInstance hello();\n","handlingStrategy":"type-guard","validationCode":"// ArchUnit/test rule: no primitive/String/Uni returns on @CheckedTemplate\nif (!TemplateInstance.class.equals(m.getReturnType())) throw new AssertionError(...);","typeGuard":"static boolean returnsTemplateInstance(Method m) {\n    return m.getReturnType() == TemplateInstance.class;\n}","tryCatchPattern":null,"preventionTips":["Never return raw domain types or reactive wrappers from checked templates","Code-review checklist item for new @CheckedTemplate methods"],"tags":["qute","checked-templates","return-type"],"backgroundTag":"checked-template-return-type","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}