{"record":{"id":"9b4ffba4ffaa29da","repo":"quarkusio/quarkus","slug":"invalid-global-variable-name-found-s-supplied","errorCode":null,"errorMessage":"Invalid global variable name found: %s\n\t- supplied by %s \n\t- a name may only consist of alphanumeric characters and underscores: ","messagePattern":"Invalid global variable name found: (.+?)\n\t- supplied by (.+?) \n\t- a name may only consist of alphanumeric characters and underscores: ","errorType":"exception","errorClass":"java.lang.IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"extensions/qute/deployment/src/main/java/io/quarkus/qute/deployment/TemplateGlobalBuildItem.java","lineNumber":25,"sourceCode":"\nimport io.quarkus.builder.item.MultiBuildItem;\nimport io.quarkus.qute.Namespaces;\nimport io.quarkus.qute.TemplateGlobal;\n\n/**\n * Represents a global variable field/method.\n *\n * @see TemplateGlobal\n */\npublic final class TemplateGlobalBuildItem extends MultiBuildItem {\n\n    private final String name;\n    private final AnnotationTarget target;\n    private final Type variableType;\n\n    public TemplateGlobalBuildItem(String name, AnnotationTarget target, Type matchType) {\n        if (!Namespaces.isValidNamespace(name)) {\n            throw new IllegalArgumentException(\n                    String.format(\n                            \"Invalid global variable name found: %s\\n\\t- supplied by %s \\n\\t- a name may only consist of alphanumeric characters and underscores: \",\n                            name,\n                            target.kind() == Kind.FIELD\n                                    ? target.asField().declaringClass().name() + \".\" + target.asField().name()\n                                    : target.asMethod().declaringClass().name() + \".\" + target.asMethod().name() + \"()\"));\n        }\n        this.name = name;\n        this.target = target;\n        this.variableType = matchType;\n    }\n\n    public AnnotationTarget getTarget() {\n        return target;\n    }\n\n    public Type getVariableType() {\n        return variableType;","sourceCodeStart":7,"sourceCodeEnd":43,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/qute/deployment/src/main/java/io/quarkus/qute/deployment/TemplateGlobalBuildItem.java#L7-L43","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Rename the field/method (or the @TemplateGlobal name value) to contain only letters, digits, and underscores","If you need a dotted/hierarchical name, use a custom namespace (@Namespace) instead of @TemplateGlobal","Rebuild with ./mvnw install to verify the fix"],"exampleFix":"// before\n@TemplateGlobal(name = \"app.config.timeout\")\nstatic int timeout() { return 30; }\n// after\n@TemplateGlobal(name = \"app_config_timeout\")\nstatic int timeout() { return 30; }","handlingStrategy":"validation","validationCode":"boolean valid = name != null && name.matches(\"[A-Za-z0-9_]+\");\nif (!valid) throw new IllegalArgumentException(\"Invalid @TemplateGlobal name: \" + name);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Only use Java identifier-style names (letters, digits, underscores) for @TemplateGlobal values","Prefer defaulting to the field/method name, which is always a valid identifier","Use @Namespace for hierarchical/dotted naming needs"],"tags":["qute","build-time","validation","naming"],"backgroundTag":"invalid-identifier-name","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}