apache/pulsar · error · IllegalArgumentException

Source namespace cannot be null

Error message

Source namespace cannot be null

What it means

validateAndExtractDetails requires SourceConfig.namespace to be non-null and non-empty because the source's fully-qualified identity is tenant/namespace/name. After the tenant check passes, a null/empty namespace aborts validation with this IllegalArgumentException.

Source

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

        if (!isEmpty(functionDetails.getRuntimeFlags())) {
            sourceConfig.setRuntimeFlags(functionDetails.getRuntimeFlags());
        }

        if (!isEmpty(functionDetails.getCustomRuntimeOptions())) {
            sourceConfig.setCustomRuntimeOptions(functionDetails.getCustomRuntimeOptions());
        }

        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());

View on GitHub (pinned to 820761864e)

Solutions

1. Set the namespace on the SourceConfig, e.g. sourceConfig.setNamespace("default")
2. If configs come from a file/template, add the missing 'namespace' entry and reload
3. Pre-validate in your own tooling: fail early with a clear message if namespace is blank before invoking Pulsar APIs

Example fix

// before
SourceConfig cfg = new SourceConfig();
cfg.setTenant("public");
cfg.setName("my-source");
// after
SourceConfig cfg = new SourceConfig();
cfg.setTenant("public");
cfg.setNamespace("default");
cfg.setName("my-source");

if (cfg.getNamespace() == null || cfg.getNamespace().isEmpty()) {
    throw new IllegalArgumentException("sourceConfig.namespace must be set (use 'default' if unsure)");
}

static boolean hasNamespace(SourceConfig cfg) {
    return cfg != null && cfg.getNamespace() != null && !cfg.getNamespace().trim().isEmpty();
}

try {
    SourceConfigUtils.validateAndExtractDetails(cfg, pkg, true);
} catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().contains("Source namespace cannot be null")) {
        // reject submission with a message asking for --namespace
    }
}

When it happens

Trigger: Calling source registration/validation with a SourceConfig that has tenant set but namespace null or empty — e.g. pulsar-admin sources create with a config file missing the 'namespace' field, or programmatic construction omitting setNamespace().

Common situations: Hand-written source config YAML missing the namespace key; code that sets tenant and name but not namespace; migrating configs between tools where one defaults the namespace and Pulsar does not.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• 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
• Source name cannot be null

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