apache/pulsar · error · IllegalArgumentException

Topic name is invalid

Error message

Topic name is invalid

What it means

When SourceConfig.topicName is set, validateAndExtractDetails checks it is a syntactically valid Pulsar topic via TopicName.isValid(). A non-null but malformed topicName (missing domain, bad characters, wrong structure) throws this IllegalArgumentException. The field is optional, but if present it must parse as a complete topic name.

Source

Thrown at pulsar-functions/utils/src/main/java/org/apache/pulsar/functions/utils/SourceConfigUtils.java:275

        }

        return sourceConfig;
    }

    public static ExtractedSourceDetails validateAndExtractDetails(SourceConfig sourceConfig,
                                                                   ValidatableFunctionPackage sourceFunction,
                                                                   boolean validateConnectorConfig) {
        if (isEmpty(sourceConfig.getTenant())) {
            throw new IllegalArgumentException("Source tenant cannot be null");
        }
        if (isEmpty(sourceConfig.getNamespace())) {
            throw new IllegalArgumentException("Source namespace cannot be null");
        }
        if (isEmpty(sourceConfig.getName())) {
            throw new IllegalArgumentException("Source name cannot be null");
        }
        if (!isEmpty(sourceConfig.getTopicName()) && !TopicName.isValid(sourceConfig.getTopicName())) {
            throw new IllegalArgumentException("Topic name is invalid");
        }
        if (!isEmpty(sourceConfig.getLogTopic())) {
            if (!TopicName.isValid(sourceConfig.getLogTopic())) {
                throw new IllegalArgumentException(
                        String.format("LogTopic topic %s is invalid", sourceConfig.getLogTopic()));
            }
        }
        if (sourceConfig.getParallelism() != null && sourceConfig.getParallelism() <= 0) {
            throw new IllegalArgumentException("Source parallelism must be a positive number");
        }
        if (sourceConfig.getResources() != null) {
            ResourceConfigUtils.validate(sourceConfig.getResources());
        }

        String sourceClassName = sourceConfig.getClassName();
        // if class name in source config is not set, this should be a built-in source
        // thus we should try to find it class name in the NAR service definition
        if (sourceClassName == null) {

View on GitHub (pinned to 820761864e)

Solutions

1. Use a fully-qualified topic name: persistent://<tenant>/<namespace>/<topic> (or non-persistent://...)
2. If you only know the short name, construct the full name with tenant/namespace, e.g. String.format("persistent://%s/%s/%s", tenant, namespace, topic)
3. Validate with TopicName.isValid(topicName) yourself before submitting so you can surface which name was rejected

Example fix

// before
cfg.setTopicName("kafka-mirror-topic");
// after
cfg.setTopicName("persistent://public/default/kafka-mirror-topic");

if (cfg.getTopicName() != null && !org.apache.pulsar.common.naming.TopicName.isValid(cfg.getTopicName())) {
    throw new IllegalArgumentException("topicName must be fully qualified, e.g. persistent://tenant/ns/topic");
}

static boolean isValidTopicName(SourceConfig cfg) {
    return cfg == null || cfg.getTopicName() == null
        || org.apache.pulsar.common.naming.TopicName.isValid(cfg.getTopicName());
}

try {
    SourceConfigUtils.validateAndExtractDetails(cfg, pkg, true);
} catch (IllegalArgumentException e) {
    if ("Topic name is invalid".equals(e.getMessage())) {
        // show the configured topicName and the expected persistent://tenant/ns/topic format
    }
}

When it happens

Trigger: Setting sourceConfig.setTopicName(...) to a string that fails TopicName.isValid — e.g. 'my-topic' (no persistent:///, tenant/namespace), 'persistent://tenant/ns/' (trailing slash, no topic), or a topic with invalid characters; then calling validateAndExtractDetails or pulsar-admin sources create.

Common situations: Users entering a bare topic name instead of a fully-qualified one; copy-pasted Kafka topic names that lack Pulsar's topic domain prefix; typos like double slashes or URL-encoded characters; assuming Pulsar will resolve a short name against a default namespace.

Related errors

• LogTopic topic %s is invalid
• When effectively once processing guarantee is specified, ret
• Only one of retain ordering or retain key ordering can be se
• Receiver queue size should be >= zero
• Source tenant cannot be null

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