apache/pulsar · error · IllegalArgumentException

Invalid named entity: ${name}

Error message

Invalid named entity: ${name}

What it means

NamedEntity.checkName validates that an entity name (tenant, namespace, topic, cluster, etc.) matches ^[-=:\.\w]*$ — only alphanumerics, underscore, and -=:. (plus URL-encoded %). Names with any other character throw IllegalArgumentException("Invalid named entity: <name>").

Source

Thrown at pulsar-common/src/main/java/org/apache/pulsar/common/naming/NamedEntity.java:37

package org.apache.pulsar.common.naming;

import java.util.regex.Matcher;
import java.util.regex.Pattern;
import lombok.experimental.UtilityClass;

/**
 */
@UtilityClass
public class NamedEntity {

    // allowed characters for property, namespace, cluster and topic names are
    // alphanumeric (a-zA-Z_0-9) and these special chars -=:.
    // % is allowed as part of valid URL encoding
    public static final Pattern NAMED_ENTITY_PATTERN = Pattern.compile("^[-=:.\\w]*$");

    public static void checkName(String name) throws IllegalArgumentException {
        if (!isAllowed(name)) {
            throw new IllegalArgumentException("Invalid named entity: " + name);
        }
    }

    public static boolean isAllowed(String name) {
        Matcher m = NAMED_ENTITY_PATTERN.matcher(name);
        return m.matches();
    }
}

View on GitHub (pinned to 820761864e)

Solutions

1. Sanitize the name to allowed characters (a-zA-Z0-9_-=:.) before passing it
2. URL-encode disallowed characters if the name must carry special data
3. Use NamedEntity.isAllowed(name) to validate before calling APIs that throw

Example fix

// before
String tenant = "my tenant/ops"; // invalid: space and slash
NamespaceName ns = NamespaceName.get(tenant + "/app");
// after
String tenant = "my-tenant-ops"; // sanitized
NamespaceName ns = NamespaceName.get(tenant + "/app");

private static final Pattern SAFE = Pattern.compile("^[-=:.\\w]*$");
if (name == null || !SAFE.matcher(name).matches()) {
    throw new IllegalArgumentException("Name contains disallowed characters: " + name);
}

boolean isValidEntityName(String name) {
    return name != null && NamedEntity.isAllowed(name);
}

try {
    NamedEntity.checkName(name);
} catch (IllegalArgumentException e) {
    throw new IllegalArgumentException("Rejecting invalid entity name (allowed: a-zA-Z0-9_-=:.): " + name, e);
}

When it happens

Trigger: Calling checkName (or APIs that call it, like tenant/namespace/topic creation) with a name containing spaces, slashes outside allowed positions, unicode, '@', '#', or other special characters.

Common situations: User-supplied names passed through unvalidated (e.g. from HTTP requests or labels), names containing '/' when the caller already split the path, email addresses or paths used as tenant names.

Related errors

• Label name '%s' is invalid: must match the regex [a-zA-Z_][a
• Namespace name is not valid
• Function Name not provided
• Cannot derive a tenant/namespace from --regex pattern '${pat
• Invalid null namespace: ${namespace}

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/21a9f18b11a9c619. Report an issue: GitHub.