quarkusio/quarkus · error · TemplateException

[" + value + "] is not a valid namespace. The value can only

Error message

[" + value + "] is not a valid namespace. The value can only consist of alphanumeric characters and underscores.

What it means

Qute namespaces (the prefix before ':' in expressions like {config:property}) must contain only alphanumeric characters and underscores. Namespaces.requireValid(String) validates user-supplied namespace values (e.g. when registering a namespace resolver) and throws TemplateException for anything else. This is a fail-fast input validation so invalid namespaces are rejected at registration time rather than producing unmatchable expressions.

Source

Thrown at independent-projects/qute/core/src/main/java/io/quarkus/qute/Namespaces.java:26

    static final Pattern NAMESPACE_PATTERN = Pattern.compile("[a-zA-Z0-9_]+");

    private Namespaces() {
    }

    public static boolean isValidNamespace(String value) {
        return NAMESPACE_PATTERN.matcher(value).matches();
    }

    public static boolean isDataNamespace(String value) {
        return DATA_NAMESPACE.equals(value);
    }

    public static String requireValid(String value) {
        if (isValidNamespace(value)) {
            return value;
        }
        throw new TemplateException("[" + value
                + "] is not a valid namespace. The value can only consist of alphanumeric characters and underscores.");
    }

}

View on GitHub (pinned to e1c734241f)

Solutions

1. Use only [a-zA-Z0-9_]+ characters for the namespace, e.g. addNamespace("config") instead of "my-config"
2. Sanitize the value before registration: strip/replace invalid characters with underscores
3. If null/blank may occur, check isValidNamespace(value) first and fail fast with a clearer application-level error
4. Register multiple aliases if you need several names, each individually valid

Example fix

// before
engineBuilder.addNamespace("my-namespace"); // hyphen -> TemplateException
// after
engineBuilder.addNamespace("my_namespace");

String ns = candidate == null ? "" : candidate;
if (!ns.matches("[a-zA-Z0-9_]+")) {
    throw new IllegalArgumentException("Invalid namespace: " + ns);
}
engineBuilder.addNamespace(ns);

boolean isValidNamespace(String v) {
    return v != null && v.matches("[a-zA-Z0-9_]+");
}

try {
    engineBuilder.addNamespace(userNamespace).build();
} catch (TemplateException e) {
    if (e.getMessage().contains("is not a valid namespace")) {
        throw new IllegalArgumentException("Namespace must be alphanumeric/underscore: " + userNamespace, e);
    }
    throw e;
}

When it happens

Trigger: Calling EngineBuilder.addNamespace(...) or Namespaces.requireValid with a value containing hyphens, dots, spaces, or starting with a digit, e.g. addNamespace("my-ns") or addNamespace("").

Common situations: Using a dotted or hyphenated namespace name by habit (like a package or config prefix); copying a namespace containing whitespace; empty string from an externalized config value.

Related errors

• Invalid template link [${templateLink}] - Expeting a link th
• Message bundle name [%s] declared on %s must be a valid name
• Invalid global variable name found: %s - supplied by %s -
• [prefix] is not a valid iteration metadata prefix. The value
• Invalid identifier found: [id]

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