apache/pulsar · error · IllegalArgumentException

Source name not specified

Error message

Source name not specified

What it means

Thrown by validateSourceConfigs after inferMissingArguments fills defaults: the SourceConfig has no name set. Every Pulsar IO source requires a unique name within its tenant/namespace so the broker can manage it. The CLI rejects the request before any server call.

Source

Thrown at pulsar-client-tools/src/main/java/org/apache/pulsar/admin/cli/CmdSources.java:540

        protected BatchSourceConfig parseBatchSourceConfigs(String str) {
            return new Gson().fromJson(str, BatchSourceConfig.class);
        }

        protected void validateSourceConfigs(SourceConfig sourceConfig) {
            if (isBlank(sourceConfig.getArchive())) {
                throw new ParameterException("Source archive not specified");
            }
            org.apache.pulsar.common.functions.Utils.inferMissingArguments(sourceConfig);
            if (!Utils.isFunctionPackageUrlSupported(sourceConfig.getArchive())
                    && !sourceConfig.getArchive().startsWith(Utils.BUILTIN)) {
                if (!new File(sourceConfig.getArchive()).exists()) {
                    throw new IllegalArgumentException(String.format("Source Archive %s does not exist",
                            sourceConfig.getArchive()));
                }
            }
            if (isBlank(sourceConfig.getName())) {
                throw new IllegalArgumentException("Source name not specified");
            }

            if (sourceConfig.getBatchSourceConfig() != null) {
                validateBatchSourceConfigs(sourceConfig.getBatchSourceConfig());
            }
        }

        protected void validateBatchSourceConfigs(BatchSourceConfig batchSourceConfig) {
            if (isBlank(batchSourceConfig.getDiscoveryTriggererClassName())) {
                throw new IllegalArgumentException("Discovery Triggerer not specified");
            }
        }

        protected String validateSourceType(String sourceType) throws IOException {
            Set<String> availableSources;
            try {
                availableSources = getAdmin().sources().getBuiltInSources().stream()
                        .map(ConnectorDefinition::getName).collect(Collectors.toSet());

View on GitHub (pinned to 820761864e)

Solutions

  1. Add --name <source-name> to the command
  2. Add a name field to the source config file
  3. Check your script/CI variable that supplies the name is not empty

Example fix

// before
pulsar-admin sources create --archive ./my-source.nar --tenant public --namespace default
// after
pulsar-admin sources create --name my-source --archive ./my-source.nar --tenant public --namespace default
Defensive patterns

Strategy: validation

Validate before calling

if (sourceConfig.getName() == null || sourceConfig.getName().isBlank()) {
    throw new IllegalArgumentException("Source name must be set before calling the CLI");
}

Type guard

boolean hasSourceName(SourceConfig cfg) {
    return cfg.getName() != null && !cfg.getName().trim().isEmpty();
}

Try / catch

try {
    admin.sources().createSource(sourceConfig);
} catch (IllegalArgumentException e) {
    System.err.println("Set --name or a name in the config file");
}

Prevention

When it happens

Trigger: Running `pulsar-admin sources create/update/localrun` without --name and without a name in the config file passed via --source-config-file.

Common situations: Forgetting the --name flag on create, a source-config YAML/JSON missing the 'name' key, or scripting the CLI where an empty variable is expanded to nothing.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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