apache/pulsar · error · CommandLine.ParameterException

end timestamp should be positive.

Error message

end timestamp should be positive.

What it means

CmdConsume.run validates endTimestamp and throws a CommandLine.ParameterException when it is negative. The end timestamp is an epoch-millis bound for consumption, so only zero (unset/absent) or positive values are accepted.

Source

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

    @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) {
        int numMessagesConsumed = 0;
        int returnCode = 0;

        final Schema<?> schema;
        if ("auto_consume".equals(schemaType)) {
            schema = Schema.autoConsume();
        } else if ("bytes".equals(schemaType)) {

View on GitHub (pinned to 820761864e)

Solutions

1. Omit --end-timestamp entirely when no end bound is wanted instead of passing a negative sentinel
2. Pass a valid positive epoch-millis value, e.g. $(date +%s000)
3. Fix the script/config so the default is 0 (unset) rather than -1

Example fix

// before
END_TS=${END_TS:--1}
pulsar-client consume ... --end-timestamp $END_TS
// after
if [ -n "$END_TS" ] && [ "$END_TS" -gt 0 ]; then
  pulsar-client consume ... --end-timestamp "$END_TS"
else
  pulsar-client consume ...
fi

if [ -n "$END_TS" ] && [ "$END_TS" -lt 0 ] 2>/dev/null; then
  echo "--end-timestamp must be a positive epoch-millis (or omit the flag)" >&2; exit 2;
fi

static boolean isValidEndTimestamp(long ts) { return ts <= 0 || ts > 0; /* 0 means unset; negatives are invalid — use ts >= 0 and omit flag for unset */
return ts >= 0; }

try {
    int rc = cmdConsume.run();
} catch (CommandLine.ParameterException e) {
    if (e.getMessage().contains("end timestamp")) {
        System.err.println("--end-timestamp must be positive epoch-millis; omit the flag for no bound");
        System.exit(2);
    } else { throw e; }
}

When it happens

Trigger: Passing --end-timestamp with a negative number, typically a miscalculated epoch value or a sentinel like -1 used to mean 'disabled'.

Common situations: Using -1 as a 'no limit' sentinel (as some tools allow) that this CLI rejects; date math in a script producing a negative epoch; reading a placeholder config value like ${END_TS} that defaults to -1.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Subscription name is not provided.
• Number of messages should be zero or positive.
• schema type must be 'bytes' or 'auto_consume'
• Number of times need to be positive number.
• ${paramName} cannot be bigger than <${maxValue}>!

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