apache/pulsar · error · IllegalArgumentException

Invalid topic name: '${topicName}'. Topic name must not have

Error message

Invalid topic name: '${topicName}'. Topic name must not have leading or trailing whitespace.

What it means

TopicName.validateTopicNameForCreation(topicName) enforces that a topic name intended for creating a new topic has no leading or trailing whitespace, as delegated to TopicName.isValidForCreation. If the check fails it throws an IllegalArgumentException naming the offending topic name. This prevents creating topics whose names contain invisible padding that causes lookup/management mismatches.

Source

Thrown at pulsar-common/src/main/java/org/apache/pulsar/common/naming/TopicName.java:136

     * allowed.
     *
     * <p>This is only meant to be checked on topic creation paths, so topics which already have such a name
     * remain listable, readable and deletable.
     */
    public static boolean isValidForCreation(TopicName topicName) {
        String topic = topicName.toString();
        return topic.equals(StringUtils.trim(topic));
    }

    /**
     * Validates that a topic name can be used to create a new topic.
     *
     * @throws IllegalArgumentException if the topic name cannot be used to create a topic
     * @see #isValidForCreation(TopicName)
     */
    public static void validateTopicNameForCreation(TopicName topicName) {
        if (!isValidForCreation(topicName)) {
            throw new IllegalArgumentException("Invalid topic name: '" + topicName
                    + "'. Topic name must not have leading or trailing whitespace.");
        }
    }

    public static String getPartitionPattern(String topic) {
        return "^" + Pattern.quote(get(topic).getPartitionedTopicName().toString()) + "-partition-[0-9]+$";
    }

    public static String getPattern(String topic) {
        return "^" + Pattern.quote(get(topic).getPartitionedTopicName().toString()) + "$";
    }

    @SuppressFBWarnings("DCN_NULLPOINTER_EXCEPTION")
    private TopicName(String completeTopicName) {
        try {
            // The topic name can be in two different forms, one is fully qualified topic name,
            // the other one is short topic name
            int index = completeTopicName.indexOf("://");

View on GitHub (pinned to 820761864e)

Solutions

Trim the topic-name string before constructing the TopicName: topicName.trim().
Fix the configuration/script source so the value is quoted or stripped of whitespace.
Call TopicName.isValidForCreation(topicName) yourself first and reject or sanitize bad input with a clear message.
If the whitespace is intentional in an existing topic's name, address the root data problem rather than bypassing the validation.

Example fix

// before
TopicName t = TopicName.get(" persistent://public/default/my-topic ");
TopicName.validateTopicNameForCreation(t);
// after
String raw = " persistent://public/default/my-topic ".trim();
TopicName t = TopicName.get(raw);
TopicName.validateTopicNameForCreation(t);

Defensive patterns

Strategy: validation

Validate before calling

String raw = input.trim();
TopicName t = TopicName.get(raw);
if (!TopicName.isValidForCreation(t)) {
    throw new IllegalArgumentException("Topic name has surrounding whitespace: '" + input + "'");
}
TopicName.validateTopicNameForCreation(t);

Type guard

static boolean isCleanForCreation(String topic) {
    return topic != null && topic.trim().equals(topic) && !topic.isEmpty();
}

Try / catch

try {
    TopicName.validateTopicNameForCreation(topicName);
} catch (IllegalArgumentException e) {
    log.error("Refusing to create topic: {}", e.getMessage());
    throw e; // do not silently trim — surface the bad input
}

Prevention

Trim all topic-name inputs at the boundary (CLI args, REST params, config parsing).
Quote YAML/properties values so trailing whitespace is not silently dropped or preserved inconsistently.
Run TopicName.isValidForCreation as a pre-flight check before any create-topic admin call.

When it happens

Trigger: Calling validateTopicNameForCreation on a TopicName built from a string with leading/trailing spaces, e.g. ' persistent://public/default/my-topic ' or a non-persistent name with trailing whitespace from user input or a config file.

Common situations: Topic names copy-pasted from docs or terminals with trailing spaces; YAML/properties values with unquoted trailing whitespace; shell scripts interpolating variables that carry stray spaces; admin CLI arguments pasted with whitespace.

Related errors

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