What causes " # () must declare a parameter of name [ ] and type [ ]" in quarkusio/quarkus?

Add or rename the @CheckedTemplate method parameter so its name exactly matches the key used in the template

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

<Class>#<method>() must declare a parameter of name [<paramN

Error message

<Class>#<method>() must declare a parameter of name [<paramName>] and type [<type>]

What it means

Thrown during validation of type-safe templates/fragments when a template parameter key or checked fragment parameter cannot be matched to a method parameter of the @CheckedTemplate method/constructor, or the declared types are not assignable. Qute type-checks template data against the parameters of the checked template method.

Source

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

                            }
                        }
                    }
                }
            }
            if (!paramNamesToTypes.isEmpty()) {
                for (Entry<String, Type> e : paramNamesToTypes.entrySet()) {
                    String paramName = e.getKey();
                    MethodInfo methodOrConstructor = null;
                    if (validation.checkedTemplate.isRecord()) {
                        methodOrConstructor = validation.checkedTemplate.recordClass
                                .canonicalRecordConstructor();
                    } else {
                        methodOrConstructor = validation.checkedTemplate.method;
                    }
                    MethodParameterInfo param = methodOrConstructor.parameters().stream()
                            .filter(mp -> mp.name().equals(paramName)).findFirst().orElse(null);
                    if (param == null || !assignabilityCheck.isAssignableFrom(e.getValue(), param.type())) {
                        throw new TemplateException(
                                validation.checkedTemplate.method.declaringClass().name().withoutPackagePrefix() + "#"
                                        + validation.checkedTemplate.method.name() + "() must declare a parameter of name ["
                                        + paramName
                                        + "] and type [" + e.getValue() + "]");
                    }
                }
            }
        }
    }

    @BuildStep(onlyIf = IsTest.class)
    SyntheticBeanBuildItem registerRenderedResults(QuteConfig config) {
        if (config.testMode().recordRenderedResults()) {
            return SyntheticBeanBuildItem.configure(RenderedResults.class)
                    .unremovable()
                    .scope(Singleton.class)
                    .creator(RenderedResultsCreator.class)
                    .done();

View on GitHub (pinned to e1c734241f)

Solutions

Add or rename the @CheckedTemplate method parameter so its name exactly matches the key used in the template
Make the declared parameter type assignable from the value type used in the template expression
If the mismatch is intentional, adjust the template to use the declared parameter name/type
Compile with -parameters (Quarkus does by default) so method parameter names are preserved for matching

Example fix

// before
@CheckedTemplate
static class Templates {
    public static native TemplateInstance page(String userName); // template uses {name}
}

// after
@CheckedTemplate
static class Templates {
    public static native TemplateInstance page(String name); // matches {name} in page.html
}

Defensive patterns

Strategy: validation

Validate before calling

// Ensure every data key used in the template has a matching method parameter
Set<String> paramNames = method.parameters().stream().map(p -> p.name()).collect(Collectors.toSet());
Set<String> templateKeys = extractKeys(templateBody); // e.g. {name}, {item:price}
templateKeys.removeAll(paramNames);
if (!templateKeys.isEmpty()) { throw new IllegalStateException("Missing params: " + templateKeys); }

Prevention

Add the method parameter first, then use it in the template
Use type-safe checked templates instead of string-based data maps
Avoid renaming parameters without grepping the template for the old name
Keep -parameters compilation enabled (Quarkus default)

When it happens

Trigger: The template references a data key (e.g. {name}) for which the @CheckedTemplate method declares no parameter with that name; a parameter exists but its type is not assignable from the value type recorded in the template validation; parameter name info lost at compile time so names do not match.

Common situations: Adding a new data key to a template without adding the corresponding method parameter; renaming a Java parameter but not the template; compiling without -parameters so parameter names differ; passing a subtype/supertype mismatch in a fragment validation.

Related errors

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