apache/pulsar · error · IllegalArgumentException

Metadata store address argument is required (--metadata-stor

Error message

Metadata store address argument is required (--metadata-store)

What it means

PulsarClusterMetadataTeardown wipes cluster metadata (ZooKeeper/metadata store contents) before removing the cluster. The tool needs the address of the metadata store to connect to; if neither --metadata-store nor the legacy --zookeeper argument is supplied, it aborts before doing anything. This is a fail-fast guard so the tool never connects to an unintended or default metadata service.

Source

Thrown at pulsar-broker/src/main/java/org/apache/pulsar/PulsarClusterMetadataTeardown.java:125

            commander.parseArgs(args);
            if (arguments.help) {
                commander.usage(commander.getOut());
                return;
            }
            if (arguments.generateDocs) {
                CmdGenerateDocs cmd = new CmdGenerateDocs("pulsar");
                cmd.addCommand("delete-cluster-metadata", commander);
                cmd.run(null);
                return;
            }
        } catch (Exception e) {
            commander.getErr().println(e);
            throw e;
        }

        if (arguments.metadataStoreUrl == null && arguments.zookeeper == null) {
            commander.usage(commander.getOut());
            throw new IllegalArgumentException("Metadata store address argument is required (--metadata-store)");
        }

        if (arguments.metadataStoreUrl == null) {
            arguments.metadataStoreUrl = ZKMetadataStore.ZK_SCHEME_IDENTIFIER + arguments.zookeeper;
        }

        @Cleanup
        MetadataStoreExtended metadataStore = MetadataStoreExtended.create(arguments.metadataStoreUrl,
                MetadataStoreConfig.builder()
                        .sessionTimeoutMillis(arguments.zkSessionTimeoutMillis)
                        .metadataStoreName(MetadataStoreConfig.METADATA_STORE)
                        .configFilePath(arguments.metadataStoreConfigPath)
                        .build());

        if (arguments.bkMetadataServiceUri != null) {
            @Cleanup
            BookKeeper bookKeeper =
                    new BookKeeper(new ClientConfiguration().setMetadataServiceUri(arguments.bkMetadataServiceUri));

View on GitHub (pinned to 820761864e)

Solutions

Re-run with --metadata-store, e.g. `bin/pulsar cluster-metadata-teardown --metadata-store zookeeper://zk1:2181` (or the configured metadataStoreUrl from broker.conf).
If you are on an older ZooKeeper-based setup and still have the legacy flag available, pass `--zookeeper zk1:2181`; it is converted to a zookeeper:// metadata store URL automatically.
Check your automation/env so the URL variable is actually set (empty shell variables are a common silent cause).
Run with --help to see the exact accepted flags for your Pulsar version.

Example fix

// before
bin/pulsar cluster-metadata-teardown

// after
bin/pulsar cluster-metadata-teardown --metadata-store zookeeper://zk1:2181

Defensive patterns

Strategy: validation

Validate before calling

String metadataStoreUrl = System.getProperty("pulsar.metadatastore.url");
if ((metadataStoreUrl == null || metadataStoreUrl.isEmpty())
        && (zookeeperArg == null || zookeeperArg.isEmpty())) {
    throw new IllegalArgumentException(
        "cluster-metadata-teardown requires --metadata-store or --zookeeper");
}

Try / catch

try {
    teardown.main(args);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("--metadata-store")) {
        System.err.println("Usage: --metadata-store <scheme://host:port> (or legacy --zookeeper <host:port>)");
    }
    throw e;
}

Prevention

Always pass --metadata-store explicitly in scripts; never rely on legacy --zookeeper.
Source the metadata store URL from the broker.conf (metadataStoreUrl=...) rather than typing it.
Validate shell variables are non-empty before interpolating them into CLI args.
Run `pulsar cluster-metadata-teardown --help` when upgrading versions to catch flag renames.

When it happens

Trigger: Running `pulsar cluster-metadata-teardown` (main() via JCommander) without either: (a) the --metadata-store <url> argument, or (b) the legacy --zookeeper <host:port> argument. arguments.metadataStoreUrl == null && arguments.zookeeper == null in main().

Common situations: Following an old tutorial or script that only passed --zookeeper (removed/renamed in newer versions); running the teardown command with no arguments at all; copy-pasting a start command instead of the teardown command; automation scripts where the variable holding the URL is empty.

Related errors

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