{"record":{"id":"d1d3fc4d3660e352","repo":"quarkusio/quarkus","slug":"message-bundle-name-s-declared-on-s-must-be-a","errorCode":null,"errorMessage":"Message bundle name [%s] declared on %s must be a valid namespace - the value can only consist of alphanumeric characters and underscores","messagePattern":"Message bundle name \\[(.+?)\\] declared on (.+?) must be a valid namespace - the value can only consist of alphanumeric characters and underscores","errorType":"exception","errorClass":"MessageBundleException","httpStatus":null,"severity":"error","filePath":"extensions/qute/deployment/src/main/java/io/quarkus/qute/deployment/MessageBundleProcessor.java","lineNumber":180,"sourceCode":"                            // declaring classes in the hierarchy separated by underscores\n                            List<String> names = new ArrayList<>();\n                            names.add(bundleClass.simpleName());\n                            DotName enclosingName = bundleClass.enclosingClass();\n                            while (enclosingName != null) {\n                                ClassInfo enclosingClass = index.getClassByName(enclosingName);\n                                if (enclosingClass != null) {\n                                    names.add(enclosingClass.simpleName());\n                                    enclosingName = enclosingClass.nestingType() == NestingType.TOP_LEVEL ? null\n                                            : enclosingClass.enclosingClass();\n                                }\n                            }\n                            Collections.reverse(names);\n                            name = String.join(\"_\", names);\n                        }\n                        LOG.debugf(\"Message bundle %s: name defaulted to %s\", bundleClass, name);\n                    }\n                    if (!Namespaces.isValidNamespace(name)) {\n                        throw new MessageBundleException(\n                                String.format(\n                                        \"Message bundle name [%s] declared on %s must be a valid namespace - the value can only consist of alphanumeric characters and underscores\",\n                                        name, bundleClass));\n                    }\n\n                    if (found.containsKey(name)) {\n                        throw new MessageBundleException(\n                                String.format(\"Message bundle interface name conflict - [%s] is used for both [%s] and [%s]\",\n                                        name, bundleClass, found.get(name)));\n                    }\n                    found.put(name, bundleClass);\n\n                    // Find localizations for each interface\n                    String defaultLocale = getDefaultLocale(bundleAnnotation, locales);\n                    List<ClassInfo> localized = new ArrayList<>();\n                    for (ClassInfo implementor : index.getKnownDirectSubinterfaces(bundleClass.name())) {\n                        localized.add(implementor);\n                    }","sourceCodeStart":162,"sourceCodeEnd":198,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/qute/deployment/src/main/java/io/quarkus/qute/deployment/MessageBundleProcessor.java#L162-L198","documentation":"MessageBundleException thrown at build time by MessageBundleProcessor when the name given in @MessageBundle (or a defaulted name derived from nested class names) is not a valid Qute namespace. A bundle name becomes the template namespace (e.g. {msg:hello()}), so it may contain only alphanumeric characters and underscores. An invalid name would produce unreachable or malformed template expressions, so the build fails fast.","triggerScenarios":"Annotating an interface with @MessageBundle(value = \"my-bundle\") (hyphen, dot, space or other non-alphanumeric characters), or a nested interface whose auto-derived name joins enclosing class simple names with underscores producing characters outside [alnum_].","commonSituations":"Using kebab-case names by habit (e.g. \"app-messages\"); copying names with dots like \"app.messages\"; putting locale suffixes into the name; nesting bundle interfaces inside inner classes and assuming any name works.","solutions":["Rename the bundle to only alphanumeric/underscore characters, e.g. @MessageBundle(value = \"app_messages\").","If relying on the default name, move the interface to top level (name becomes 'msg') or rename enclosing/nested classes so the derived name is valid.","Update all templates using the old namespace (e.g. {app-bundle:key} -> {app_messages:key})."],"exampleFix":"// before\n@MessageBundle(value = \"app-messages\")\npublic interface AppMessages { @Message String hello(); }\n\n// after\n@MessageBundle(value = \"app_messages\")\npublic interface AppMessages { @Message String hello(); }","handlingStrategy":"validation","validationCode":"String name = bundleAnnotation.value();\nif (name != null && !name.matches(\"[A-Za-z0-9_]+\")) {\n    throw new IllegalArgumentException(\"Bundle name must be alphanumeric/underscore: \" + name);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use only [a-z0-9_] in bundle names; never hyphens or dots.","Rely on the default name for simple cases (top-level interface -> \"msg\").","Search templates for the old namespace after any rename to keep names in sync.","Note the derived name of nested bundles joins enclosing class simple names with underscores — keep class names alphanumeric."],"tags":["quarkus","qute","message-bundle","namespace","build-time"],"backgroundTag":"invalid-namespace-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"}