What causes "You must specify a name for the source" in apache/pulsar?

Pass --name on the command line

apache/pulsar · error · RuntimeException

You must specify a name for the source

Error message

You must specify a name for the source

What it means

Thrown by processArguments of the source command when no source name was provided at all. Unlike validateSourceConfigs (which checks the config object after defaults are inferred), this is the earlier check on the parsed CLI argument: a name is mandatory for the operation to identify the source. It surfaces as a RuntimeException from the command's argument processing.

Source

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

        protected String tenant;

        @Option(names = "--namespace", description = "The source's namespace")
        protected String namespace;

        @Option(names = "--name", description = "The source's name")
        protected String sourceName;

        @Override
        void processArguments() throws Exception {
            super.processArguments();
            if (tenant == null) {
                tenant = PUBLIC_TENANT;
            }
            if (namespace == null) {
                namespace = DEFAULT_NAMESPACE;
            }
            if (null == sourceName) {
                throw new RuntimeException(
                            "You must specify a name for the source");
            }
        }
    }

    @Command(description = "Stops a Pulsar IO source connector")
    protected class DeleteSource extends SourceCommand {

        @Override
        void runCmd() throws Exception {
            getAdmin().sources().deleteSource(tenant, namespace, sourceName);
            print("Delete source successfully");
        }
    }

    @Command(description = "Gets the information about a Pulsar IO source connector")
    protected class GetSource extends SourceCommand {

View on GitHub (pinned to 820761864e)

Solutions

Pass --name <source-name> on the command line
Ensure the scripted variable supplying the name is non-empty
Include a name in the source config file and verify it is loaded

Example fix

// before
pulsar-admin sources delete --tenant public --namespace default
// after
pulsar-admin sources delete --name my-source --tenant public --namespace default

Defensive patterns

Strategy: validation

Validate before calling

if (sourceName == null || sourceName.isBlank()) {
    throw new IllegalArgumentException("--name is required");
}

Type guard

boolean hasName(String name) {
    return name != null && !name.trim().isEmpty();
}

Try / catch

try {
    admin.sources().updateSource(config);
} catch (RuntimeException e) {
    System.err.println("Supply --name: " + e.getMessage());
}

Prevention

Treat --name as mandatory in all sources subcommands
Fail fast in wrapper scripts when the name variable is empty
Keep source names consistent between create and update commands

When it happens

Trigger: Invoking `pulsar-admin sources create/update/delete/get/status/localrun` without --name (or the positional name argument), so sourceName is null after argument parsing.

Common situations: Forgetting the --name flag, CI scripts with empty variables, copy-pasting commands and deleting the name, or confusing --source-config-file (which may lack a name) with providing --name.

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/8092897c759fbe8f. Report an issue: GitHub.