apache/pulsar · error · ParameterException

Option --version must be greater than 0, but found %d

Error message

Option --version must be greater than 0, but found %d

What it means

When using `pulsar-admin schemas get --version`, the version must be non-negative; a negative value is rejected with this ParameterException. Note the message says 'greater than 0' while the check is version < 0, so 0 itself is accepted.

Source

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

        private String topicName;

        @Option(names = {"-v", "--version"}, description = "version", required = false)
        private Long version;

        @Option(names = {"-a", "--all-version"}, description = "all version", required = false)
        private boolean all = false;

        @Override
        void run() throws Exception {
            String topic = validateTopicName(topicName);
            if (version != null && all) {
                throw new ParameterException("Only one or neither of --version and --all-version can be specified.");
            }
            if (version == null && !all) {
                System.out.println(getAdmin().schemas().getSchemaInfoWithVersion(topic));
            } else if (!all) {
                if (version < 0) {
                    throw new ParameterException("Option --version must be greater than 0, but found " + version);
                }
                System.out.println(getAdmin().schemas().getSchemaInfo(topic, version));
            } else {
                print(getAdmin().schemas().getAllSchemas(topic));
            }
        }
    }

    @Command(description = "Get the schema for a topic")
    private class GetSchemaMetadata extends CliCommand {
        @Parameters(description = "persistent://tenant/namespace/topic", arity = "1")
        private String topicName;

        @Override
        void run() throws Exception {
            String topic = validateTopicName(topicName);
            print(getAdmin().schemas().getSchemaMetadata(topic));
        }

View on GitHub (pinned to 820761864e)

Solutions

1. Omit --version to fetch the latest schema instead of passing a negative version
2. Pass a valid non-negative version number obtained from schema version info
3. Fix the script sentinel: use absence of the flag for 'latest' rather than -1

Example fix

// before
pulsar-admin schemas get --topic t --version -1
// after
pulsar-admin schemas get --topic t   # latest
# or
pulsar-admin schemas get --topic t --version 0

if (version != null && version < 0) {
    throw new IllegalArgumentException("Schema version must be >= 0");
}

try {
    SchemaInfo info = admin.schemas().getSchemaInfo(topic, version);
} catch (org.apache.pulsar.client.admin.PulsarAdminException e) {
    // fall back to latest schema
}

When it happens

Trigger: Running schemas get with --version -1 or any negative number, often from a variable initialized to -1 as a sentinel.

Common situations: Scripts using -1 to mean 'latest' (which is the behavior when the flag is omitted, not when set negative); arithmetic producing negative versions; copying conventions from client APIs where -1 means latest.

Understand the failure class

Background: "must be positive", "Invalid value": how libraries reject invalid parameter values (ValueError, ArgumentError, INVALID_PARAMETER_VALUE) — this error's family across 28 libraries.

Related errors

• Only one or neither of --version and --all-version can be sp
• Invalid schema type %s. Valid options are: avro, json
• schema type must be 'bytes' or 'auto_consume'
• Invalid schema type: ${valueSchema}
• schema type must be 'bytes' or 'auto_consume'

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