quarkusio/quarkus · error · java.lang.IllegalArgumentException

Invalid global variable name found: %s - supplied by %s -

Error message

Invalid global variable name found: %s
	- supplied by %s 
	- a name may only consist of alphanumeric characters and underscores: 

What it means

At build time Quarkus Qute validates every @TemplateGlobal annotated field/method name. Names become Qute global variable names, which must match Qute namespace rules: alphanumeric characters and underscores only. The TemplateGlobalBuildItem constructor throws IllegalArgumentException when Namespaces.isValidNamespace(name) rejects the name.

Source

Thrown at extensions/qute/deployment/src/main/java/io/quarkus/qute/deployment/TemplateGlobalBuildItem.java:25

import io.quarkus.builder.item.MultiBuildItem;
import io.quarkus.qute.Namespaces;
import io.quarkus.qute.TemplateGlobal;

/**
 * Represents a global variable field/method.
 *
 * @see TemplateGlobal
 */
public final class TemplateGlobalBuildItem extends MultiBuildItem {

    private final String name;
    private final AnnotationTarget target;
    private final Type variableType;

    public TemplateGlobalBuildItem(String name, AnnotationTarget target, Type matchType) {
        if (!Namespaces.isValidNamespace(name)) {
            throw new IllegalArgumentException(
                    String.format(
                            "Invalid global variable name found: %s\n\t- supplied by %s \n\t- a name may only consist of alphanumeric characters and underscores: ",
                            name,
                            target.kind() == Kind.FIELD
                                    ? target.asField().declaringClass().name() + "." + target.asField().name()
                                    : target.asMethod().declaringClass().name() + "." + target.asMethod().name() + "()"));
        }
        this.name = name;
        this.target = target;
        this.variableType = matchType;
    }

    public AnnotationTarget getTarget() {
        return target;
    }

    public Type getVariableType() {
        return variableType;

View on GitHub (pinned to e1c734241f)

Solutions

1. Rename the field/method (or the @TemplateGlobal name value) to contain only letters, digits, and underscores
2. If you need a dotted/hierarchical name, use a custom namespace (@Namespace) instead of @TemplateGlobal
3. Rebuild with ./mvnw install to verify the fix

Example fix

// before
@TemplateGlobal(name = "app.config.timeout")
static int timeout() { return 30; }
// after
@TemplateGlobal(name = "app_config_timeout")
static int timeout() { return 30; }

boolean valid = name != null && name.matches("[A-Za-z0-9_]+");
if (!valid) throw new IllegalArgumentException("Invalid @TemplateGlobal name: " + name);

When it happens

Trigger: Annotating a static field or method with @TemplateGlobal where the field/method name (or explicit name= value) contains a hyphen, dot, space, or other non-alphanumeric character. The build step constructs a TemplateGlobalBuildItem with that name and the constructor throws immediately.

Common situations: Copy-pasting a Java constant style name like 'my-global' or 'app.config' into @TemplateGlobal(name=...); renaming refactors leaving invalid characters in the name; misreading the annotation contract and using qualified names.

Related errors

• Template extension method declared on must not return void:
• The app name '%s' is not valid. The <appName> only allow alp
• Invalid fileName
• CardAction title is required
• CardText requires either staticText(), dynamicText(), or str

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