apache/pulsar · error · CommandLine.ParameterException

Subscription name is not provided.

Error message

Subscription name is not provided.

What it means

CmdConsume.run validates command-line state before connecting and throws a picocli CommandLine.ParameterException if the subscription name is null or empty. A Pulsar consumer must be attached to a subscription, so the CLI refuses to proceed without one.

Source

Thrown at pulsar-client-tools/src/main/java/org/apache/pulsar/client/cli/CmdConsume.java:160

    @Option(names = { "-etp", "--end-timestamp" }, description = "End timestamp for consuming messages")
    private long endTimestamp = Long.MAX_VALUE;

    public CmdConsume() {
        // Do nothing
        super();
    }

    @Spec
    private CommandSpec commandSpec;

    /**
     * Run the consume command.
     *
     * @return 0 for success, < 0 otherwise
     */
    public int run() throws IOException {
        if (this.subscriptionName == null || this.subscriptionName.isEmpty()) {
            throw new CommandLine.ParameterException(commandSpec.commandLine(), "Subscription name is not provided.");
        }
        if (this.numMessagesToConsume < 0) {
            throw new CommandLine.ParameterException(commandSpec.commandLine(),
                    "Number of messages should be zero or positive.");
        }
        if (this.endTimestamp < 0) {
            throw new CommandLine.ParameterException(commandSpec.commandLine(),
                    "end timestamp should be positive.");
        }

        if (this.serviceURL.startsWith("ws")) {
            return consumeFromWebSocket(topic);
        } else {
            return consume(topic);
        }
    }

    private int consume(String topic) {

View on GitHub (pinned to 820761864e)

Solutions

1. Pass a subscription name: --subscription my-sub (or -s my-sub)
2. Fix shell/config interpolation so the variable holding the subscription is not empty
3. Wrap the invocation to fail fast: check the argument before calling the CLI

Example fix

// before
pulsar-client consume persistent://public/default/topic --num-messages 10
// after
pulsar-client consume persistent://public/default/topic -s my-sub --num-messages 10

if [ -z "$SUB" ]; then echo "subscription (-s) is required" >&2; exit 2; fi
pulsar-client consume ... -s "$SUB"

try (PulsarClient cli = ...) {
    int rc = cmdConsume.run();
} catch (CommandLine.ParameterException e) {
    System.err.println("Usage error: " + e.getMessage());
    System.exit(2);
}

When it happens

Trigger: Running the consume command without --subscription (or with -s '' ), so this.subscriptionName ends up null/empty when run() executes.

Common situations: Forgotten -s flag in scripts/CI; config template where the subscription variable expands to empty string; renaming the flag in a newer CLI version while old scripts still omit it.

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

• Number of messages should be zero or positive.
• Number of times need to be positive number.
• end timestamp should be positive.
• schema type must be 'bytes' or 'auto_consume'
• Please supply message content with either --messages or --fi

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