apache/pulsar · error · IllegalArgumentException

Need to specify a configuration file for broker

Error message

Need to specify a configuration file for broker

What it means

PulsarBrokerStarter.call performs argument validation before initializing the broker: if starterArguments.brokerConfigFile is blank, the command usage is printed and this IllegalArgumentException is thrown. A broker cannot start without its configuration file.

Source

Thrown at pulsar-broker/src/main/java/org/apache/pulsar/PulsarBrokerStarter.java:170

        }

        public Integer call() throws Exception {
            if (starterArguments.help) {
                commander.usage(commander.getOut());
                return 0;
            }

            if (starterArguments.generateDocs) {
                CmdGenerateDocs cmd = new CmdGenerateDocs("pulsar");
                cmd.addCommand("broker", commander);
                cmd.run(null);
                return 0;
            }

            // init broker config
            if (isBlank(starterArguments.brokerConfigFile)) {
                commander.usage(commander.getOut());
                throw new IllegalArgumentException("Need to specify a configuration file for broker");
            } else {
                final String filepath = Path.of(starterArguments.brokerConfigFile)
                        .toAbsolutePath().normalize().toString();
                brokerConfig = loadConfig(filepath);
            }

            int maxFrameSize = brokerConfig.getMaxMessageSize() + Commands.MESSAGE_SIZE_FRAME_PADDING;
            if (maxFrameSize >= DirectMemoryUtils.jvmMaxDirectMemory()) {
                throw new IllegalArgumentException("Max message size need smaller than jvm directMemory");
            }

            if (!NamespaceBundleSplitAlgorithm.AVAILABLE_ALGORITHMS.containsAll(
                    brokerConfig.getSupportedNamespaceBundleSplitAlgorithms())) {
                throw new IllegalArgumentException(
                        "The given supported namespace bundle split algorithm has unavailable algorithm. "
                                + "Available algorithms are " + NamespaceBundleSplitAlgorithm.AVAILABLE_ALGORITHMS);
            }

View on GitHub (pinned to 820761864e)

Solutions

  1. Pass the broker config explicitly: --broker-config /path/to/broker.conf (or -c)
  2. Set PULSAR_STANDALONE/launcher script variables so the config path is always supplied
  3. Check the wrapper script/alias to ensure the argument is not dropped when empty

Example fix

// before
exec $PULSAR_HOME/bin/pulsar broker
// after
exec $PULSAR_HOME/bin/pulsar broker --broker-config $PULSAR_HOME/conf/broker.conf
Defensive patterns

Strategy: validation

Validate before calling

if (args.length == 0 || Arrays.stream(args)
        .noneMatch(a -> a.equals("-c") || a.equals("--broker-config"))) {
    throw new IllegalArgumentException("--broker-config is required");
}

Try / catch

try {
    int rc = starter.call();
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("configuration file for broker")) {
        commander.usage(commander.getOut());
        System.exit(2);
    }
    throw e;
}

Prevention

When it happens

Trigger: Launching the broker process without -c/--broker-config; the argument is present but empty.

Common situations: Forgetting --broker-config in systemd/launcher scripts; using a wrapper script that drops empty arguments; running 'pulsar broker' manually without options.

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/6d04eb342d0e6b4f. Report an issue: GitHub.