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

Invalid annotation target for @TemplateGlobal: <annotation>

Error message

Invalid annotation target for @TemplateGlobal: <annotation>

What it means

Thrown when @TemplateGlobal is found on an element other than a class, field, or method (e.g. a parameter or constructor). Qute only processes @TemplateGlobal on types, fields producing global variables, and static methods producing computed globals.

Source

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

    @BuildStep
    void collectTemplateGlobals(BeanArchiveIndexBuildItem beanArchiveIndex, BuildProducer<TemplateGlobalBuildItem> globals) {
        IndexView index = beanArchiveIndex.getIndex();
        Map<String, TemplateGlobalBuildItem> nameToGlobal = new HashMap<>();
        for (AnnotationInstance annotation : index.getAnnotations(TemplateGlobalGenerator.TEMPLATE_GLOBAL)) {
            switch (annotation.target().kind()) {
                case CLASS:
                    addGlobalClass(annotation.target().asClass(), nameToGlobal);
                    break;
                case FIELD:
                    addGlobalField(annotation.value(TemplateGlobalGenerator.NAME), annotation.target().asField(), nameToGlobal);
                    break;
                case METHOD:
                    addGlobalMethod(annotation.value(TemplateGlobalGenerator.NAME), annotation.target().asMethod(),
                            nameToGlobal);
                    break;
                default:
                    throw new TemplateException("Invalid annotation target for @TemplateGlobal: " + annotation);
            }
        }
        nameToGlobal.values().forEach(globals::produce);
    }

    private void addGlobalClass(ClassInfo clazz, Map<String, TemplateGlobalBuildItem> nameToGlobal) {
        for (FieldInfo field : clazz.fields()) {
            if (Modifier.isStatic(field.flags())
                    && !Modifier.isPrivate(field.flags())
                    && !field.isSynthetic()
                    && !field.hasAnnotation(TemplateGlobalGenerator.TEMPLATE_GLOBAL)) {
                addGlobalField(null, field, nameToGlobal);
            }
        }
        for (MethodInfo method : clazz.methods()) {
            if (Modifier.isStatic(method.flags())
                    && !Modifier.isPrivate(method.flags())
                    && method.returnType().kind() != org.jboss.jandex.Type.Kind.VOID

View on GitHub (pinned to e1c734241f)

Solutions

1. Apply @TemplateGlobal only to a class, a field, or a supported static method
2. For a computed global, use a public static method annotated with @TemplateGlobal (optionally with @TemplateGlobal.Enum for params)
3. Remove the annotation from the unsupported element
4. Make sure a meta-annotated custom annotation's @Target restricts to TYPE, FIELD, METHOD

Example fix

// before
class Globals {
    void init(@TemplateGlobal String user) { } // parameter target
}

// after
class Globals {
    @TemplateGlobal
    static String user() { return currentUser(); }
}

// @TemplateGlobal is valid on class, field, or supported static method only
if (!(element instanceof Class || element instanceof Field
      || (element instanceof Method m && Modifier.isStatic(m.getModifiers())))) {
    throw new IllegalArgumentException("Unsupported @TemplateGlobal target");
}

When it happens

Trigger: Annotating a constructor or method parameter with @TemplateGlobal; a custom annotation meta-annotated with @TemplateGlobal whose target resolves to an unsupported element kind in the processor's switch (CLASS/METHOD handled, default throws).

Common situations: Misreading @TemplateGlobal as a CDI qualifier and putting it on injection points; IDE auto-completion applying it to parameters; refactorings that moved the annotation down to a parameter.

Related errors

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

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