apache/pulsar · error · org.apache.pulsar.broker.admin.RestException

Namespace name is not valid

Error message

Namespace name is not valid

What it means

AdminResource.validateNamespaceName parses tenant and namespace components into a NamespaceName. If the combination violates namespace naming rules, NamespaceName.get throws IllegalArgumentException, which is converted to HTTP 412 'Namespace name is not valid'. Valid namespace names are tenant/localName where localName is up to 255 chars with allowed characters [a-zA-Z0-9_.-].

Source

Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/AdminResource.java:216

                                .log("Fail to create topic partition");
                        result.completeExceptionally(ex.getCause());
                    }
                    return null;
                });
        pulsar().getBrokerService().getTopicEventsDispatcher()
                .notifyOnCompletion(result, topicName.getPartition(partition).toString(), TopicEvent.CREATE);
        return result;
    }

    protected void validateNamespaceName(String tenant, String namespace) {
        try {
            this.namespaceName = NamespaceName.get(tenant, namespace);
        } catch (IllegalArgumentException e) {
            log.warn()
                    .attr("tenant", tenant)
                    .attr("namespace", namespace)
                    .log("Invalid namespace name");
            throw new RestException(Status.PRECONDITION_FAILED, "Namespace name is not valid");
        }
    }

    protected void validateGlobalNamespaceOwnership() {
        try {
            validateGlobalNamespaceOwnership(this.namespaceName);
        } catch (IllegalArgumentException e) {
            throw new RestException(Status.PRECONDITION_FAILED, "Tenant name or namespace is not valid");
        } catch (RestException re) {
            throw re;
        } catch (Exception e) {
            log.warn()
                    .attr("namespace", namespaceName)
                    .exceptionMessage(e)
                    .log("Failed to validate global cluster configuration");
            throw new RestException(Status.SERVICE_UNAVAILABLE, "Failed to validate global cluster configuration");
        }
    }

View on GitHub (pinned to 820761864e)

Solutions

1. Use a namespace local name matching [a-zA-Z0-9_.-]+ (max 255 chars), e.g. tenant/ns1.
2. Escape/validate the namespace in client scripts before building the admin URL.
3. If names come from user input, sanitize or reject invalid characters at your application's edge.
4. Check for double slashes or empty segments in the request path.

Example fix

// before
String ns = userInput.get("namespace"); // "my ns!"
admin.namespaces().createNamespace(tenant + "/" + ns);

// after
String ns = userInput.get("namespace");
if (!ns.matches("[a-zA-Z0-9_.-]+")) {
    throw new IllegalArgumentException("invalid namespace name");
}
admin.namespaces().createNamespace(tenant + "/" + ns);

boolean isValidNamespaceName(String tenant, String namespace) {
    return tenant != null && tenant.matches("[a-zA-Z0-9_.-]+")
        && namespace != null && namespace.matches("[a-zA-Z0-9_.-]+")
        && namespace.length() <= 255;
}

String requireValidNamespace(String tenantSlashNamespace) {
    String[] parts = tenantSlashNamespace.split("/", -1);
    if (parts.length != 2 || !isValidNamespaceName(parts[0], parts[1])) {
        throw new IllegalArgumentException("invalid namespace name: " + tenantSlashNamespace);
    }
    return tenantSlashNamespace;
}

try {
    admin.namespaces().createNamespace(ns);
} catch (PulsarAdminException e) {
    if (e.getStatusCode() == 412 && e.getMessage().contains("Namespace name is not valid")) {
        log.error("Namespace '{}' violates Pulsar naming rules [a-zA-Z0-9_.-]", ns);
    }
}

When it happens

Trigger: Any admin API call carrying a namespace identifier whose local name is empty, longer than 255 characters, or contains characters outside [a-zA-Z0-9_.-] (e.g. 'my ns', 'ns!', or a trailing slash producing an empty segment).

Common situations: URL-encoding mishaps where spaces or special characters reach the broker; scripts interpolating empty namespace variables; auto-generated namespace names from user input or UUIDs containing invalid characters; copy-paste errors including extra slashes.

Related errors

• Tenant name or namespace is not valid
• Failed to validate global cluster configuration
• Topic name is not valid
• Cannot create topic in system topic format!
• Need to provide a persistent topic name

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