quarkusio/quarkus · error · TemplateException

Template extension method declared on must accept at least

Error message

Template extension method declared on  must accept at least one parameter to match the base object: 

What it means

A non-namespace template extension method must take the base object as (normally the first) parameter so Qute knows which types it extends. If no BASE parameter exists, the generator cannot bind the method to a target type and throws TemplateException.

Source

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

                    indexed++;
                    params.add(new Param(method.parameterName(i), parameters.get(i), i, ParamKind.NAME));
                } else {
                    indexed++;
                    params.add(new Param(method.parameterName(i), parameters.get(i), i, ParamKind.EVAL));
                }
            }
            this.params = params;

            if (isNameParameterRequired) {
                Param nameParam = getFirst(ParamKind.NAME);
                if (nameParam == null || !nameParam.type.name().equals(DotNames.STRING)) {
                    throw new TemplateException(
                            "Template extension method declared on " + method.declaringClass().name()
                                    + " must accept at least one string parameter to match the name: " + method);
                }
            }
            if (!hasNamespace && getFirst(ParamKind.BASE) == null) {
                throw new TemplateException(
                        "Template extension method declared on " + method.declaringClass().name()
                                + " must accept at least one parameter to match the base object: " + method);
            }

            for (Param param : params) {
                if (param.kind == ParamKind.ATTR && !param.type.name().equals(DotNames.OBJECT)) {
                    throw new TemplateException(
                            "Template extension method parameter annotated with @TemplateAttribute declared on "
                                    + method.declaringClass().name()
                                    + " must be of type java.lang.Object: " + method);
                }
            }
        }

        public List<Type> parameterTypes() {
            return params.stream().map(p -> p.type).toList();
        }

View on GitHub (pinned to e1c734241f)

Solutions

1. Add a first parameter of the base type the method extends
2. Add namespace = "..." to @TemplateExtension if the method belongs to a namespace rather than extending a type
3. Remove the annotation if the method is not meant as an extension method

Example fix

// before
@TemplateExtension(matchName = "double")
static int doubleIt() { return 2; }
// after
@TemplateExtension(matchName = "double")
static int doubleIt(Integer val) { return val * 2; }

if (ext.namespace().isEmpty() && m.getParameterCount() == 0)
    throw new IllegalStateException("Non-namespace extension needs a base object parameter: " + m);

When it happens

Trigger: Declaring @TemplateExtension without namespace and without any base-object parameter (e.g. only name/attribute params); detected during ExtensionMethodGenerator construction.

Common situations: See trigger scenarios.

Related errors

• A template extension method matching multiple names or a reg
• Template extension method declared on must accept at least
• Template extension method declared on must be static:
• Template extension method declared on must not return void:
• Template extension method declared on must not be private:

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