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

Invalid annotation target for @TemplateContents: <target>

Error message

Invalid annotation target for @TemplateContents: <target>

What it means

Thrown when @TemplateContents is placed on an annotation target Qute does not support. @TemplateContents is only valid on supported elements (e.g. fields of type Template or classes used with type-safe templates); any other target fails the build.

Source

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

            } else if (annotation.target().kind() == Kind.METHOD) {
                MethodInfo method = annotation.target().asMethod();
                if (Modifier.isStatic(method.flags())
                        && Modifier.isNative(method.flags())
                        && method.declaringClass().hasAnnotation(Names.CHECKED_TEMPLATE)) {
                    AnnotationInstance checkedTemplateAnnotation = method.declaringClass()
                            .declaredAnnotation(Names.CHECKED_TEMPLATE);
                    String fragmentId = getCheckedFragmentId(method, checkedTemplateAnnotation);
                    templatePaths.produce(TemplatePathBuildItem.builder()
                            .content(annotation.value().asString())
                            .path(getCheckedTemplatePath(index.getIndex(), checkedTemplateAnnotation, fragmentId,
                                    method.declaringClass(), method) + suffix)
                            .extensionInfo(method.toString())
                            .source(JandexElementUriBuilder.getSource(method, TemplateContents.class))
                            .build());
                    continue;
                }
            }
            throw new TemplateException("Invalid annotation target for @TemplateContents: " + annotation.target());
        }
    }

    @BuildStep
    @Record(value = STATIC_INIT)
    void initialize(BuildProducer<SyntheticBeanBuildItem> syntheticBeans, QuteConfig config, QuteRecorder recorder,
            EffectiveTemplatePathsBuildItem effectiveTemplatePaths, Optional<TemplateVariantsBuildItem> templateVariants,
            TemplateRootsBuildItem templateRoots, List<TemplatePathExcludeBuildItem> templatePathExcludes) {

        Map<String, TemplateInfo> templates = new HashMap<>();
        for (TemplatePathBuildItem template : effectiveTemplatePaths.getTemplatePaths()) {
            templates.put(template.getPath(),
                    new TemplateInfo(template.getPath(),
                            template.getSource() != null ? template.getSource().toString() : null,
                            template.isFileBased() ? null : template.getContent()));
        }
        Map<String, List<String>> variants;
        if (templateVariants.isPresent()) {

View on GitHub (pinned to e1c734241f)

Solutions

1. Move @TemplateContents onto a supported target (e.g. a field of type Template or a checked template class)
2. Provide the content via the annotation's value on the supported element instead
3. Remove the annotation if inline content is not needed and use a template file
4. Check the @TemplateContents @Target meta-annotation and the Qute version for supported placements

Example fix

// before
class Pages {
    Template hello() { ... } // method target
}

// after
class Pages {
    @TemplateContents("Hello {name}!")
    Template hello;
}

// Only apply @TemplateContents on supported targets (field of type Template, checked template class)
if (!(element instanceof Field f) || !Template.class.equals(f.getType())) {
    throw new IllegalArgumentException("@TemplateContents must be on a Template field");
}

When it happens

Trigger: Applying @TemplateContents to a method, parameter, package, or other element via an inappropriate @Target use; writing a meta-annotation or custom annotation whose target Qute's processor does not handle in its switch over annotation targets.

Common situations: Refactoring where @TemplateContents moved from a field to a getter method; experimenting with inline template content on unsupported constructs; IDE quick-fix applying the annotation to the wrong element.

Related errors

• Invalid annotation target for @TemplateGlobal: <annotation>
• Unsupported target:
• Annotation ${dotName} was not expected on a target of kind $
• No suitable template variant found
• No template variant found

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