What causes "Template extension method declared on must be static: " in quarkusio/quarkus?

Add the static modifier to the extension method.

Template extension method declared on must be static:

Error message

Template extension method declared on  must be static:

What it means

Qute template extension methods (value resolvers exposed via @TemplateExtension or namespace extension methods) must be static. ExtensionMethodGenerator.validate() throws IllegalStateException during build-time bytecode generation when the annotated method is an instance method, since Qute calls the method statically without a receiver instance.

Source

Thrown at independent-projects/qute/generator/src/main/java/io/quarkus/qute/generator/ExtensionMethodGenerator.java:81

    public static final DotName TEMPLATE_EXTENSION = DotName.createSimple(TemplateExtension.class.getName());
    public static final DotName TEMPLATE_ATTRIBUTE = DotName.createSimple(TemplateExtension.TemplateAttribute.class.getName());
    public static final String SUFFIX = "_Extension" + ValueResolverGenerator.SUFFIX;
    public static final String NAMESPACE_SUFFIX = "_Namespace" + SUFFIX;

    public static final String MATCH_NAME = "matchName";
    public static final String MATCH_NAMES = "matchNames";
    public static final String MATCH_REGEX = "matchRegex";
    public static final String PRIORITY = "priority";
    public static final String NAMESPACE = "namespace";
    public static final String PATTERN = "pattern";

    public ExtensionMethodGenerator(IndexView index, ClassOutput classOutput) {
        super(index, classOutput);
    }

    public static void validate(MethodInfo method, String namespace) {
        if (!Modifier.isStatic(method.flags())) {
            throw new IllegalStateException(
                    "Template extension method declared on " + method.declaringClass().name() + "  must be static: " + method);
        }
        if (method.returnType().kind() == Kind.VOID) {
            throw new IllegalStateException("Template extension method declared on " + method.declaringClass().name()
                    + " must not return void: " + method);
        }
        if (Modifier.isPrivate(method.flags())) {
            throw new IllegalStateException("Template extension method declared on " + method.declaringClass().name()
                    + " must not be private: " + method);
        }
    }

    /**
     *
     * @param method
     * @param matchName
     * @param matchNames
     * @param matchRegex

View on GitHub (pinned to e1c734241f)

Solutions

Add the static modifier to the extension method.
If the method needs instance state, make it static and pass required values as parameters, or use a different resolver approach (e.g. a ValueResolver/template data).
Ensure the class containing the method is indexed (not needed for static fix, but the class must be part of the app).
Rebuild with ./mvnw install after the change; the error occurs during augmentation.

Example fix

// before
@TemplateExtension
String shout(String s) { return s.toUpperCase() + "!"; }
// after
@TemplateExtension
static String shout(String s) { return s.toUpperCase() + "!"; }

Defensive patterns

Strategy: validation

Validate before calling

// check before build
for (MethodInfo m : extensionMethods) {
    if (!Modifier.isStatic(m.flags())) {
        throw new IllegalStateException("@TemplateExtension method must be static: " + m);
    }
}

Try / catch

try {
    quarkusBuild augmentation...
} catch (IllegalStateException e) {
    if (e.getMessage().contains("must be static")) {
        // add 'static' to the annotated extension method
    }
}

Prevention

Always declare @TemplateExtension methods static
Do not attach @TemplateExtension to CDI bean instance methods
If state is needed, pass values as parameters or use @TemplateData/ValueResolver instead

When it happens

Trigger: Declaring a template extension method as non-static — e.g. @TemplateExtension on an instance method of a CDI bean or helper class — then running Quarkus augmentation; building templates with a namespace method that isn't static.

Common situations: Migrating an older extension style to @TemplateExtension and forgetting 'static'; adding @TemplateExtension to a regular bean method; copying an example but dropping the static modifier.

Related errors

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