apache/pulsar · error · IllegalArgumentException

No configuration file for Bookie

Error message

No configuration file for Bookie

What it means

When the broker is launched with runBookie or runBookieAutoRecovery enabled (via flags or broker.conf's enableRunBookieTogether/enableRunBookieAutoRecoveryTogether), a Bookie configuration file is mandatory. If starterArguments.bookieConfigFile is blank, the usage is printed and this IllegalArgumentException is thrown.

Source

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

                                              (exitCode) -> {
                                                  log.info()
                                                          .attr("exitCode", exitCode)
                                                          .log("Halting broker process");
                                                  ShutdownUtil.triggerImmediateForcefulShutdown(exitCode);
                                              });

            // if no argument to run bookie in cmd line, read from pulsar config
            if (!starterArguments.runBookie) {
                starterArguments.runBookie = brokerConfig.isEnableRunBookieTogether();
            }
            if (!starterArguments.runBookieAutoRecovery) {
                starterArguments.runBookieAutoRecovery = brokerConfig.isEnableRunBookieAutoRecoveryTogether();
            }

            if ((starterArguments.runBookie || starterArguments.runBookieAutoRecovery)
                    && isBlank(starterArguments.bookieConfigFile)) {
                commander.usage(commander.getOut());
                throw new IllegalArgumentException("No configuration file for Bookie");
            }

            // init stats provider
            if (starterArguments.runBookie || starterArguments.runBookieAutoRecovery) {
                checkState(isNotBlank(starterArguments.bookieConfigFile),
                    "No configuration file for Bookie");
                final String filepath = Path.of(starterArguments.bookieConfigFile)
                        .toAbsolutePath().normalize().toString();
                bookieConfig = readBookieConfFile(filepath);
                Class<? extends StatsProvider> statsProviderClass = bookieConfig.getStatsProviderClass();
                bookieStatsProvider = ReflectionUtils.newInstance(statsProviderClass);
            } else {
                bookieConfig = null;
                bookieStatsProvider = null;
            }

            // init bookie server
            if (starterArguments.runBookie) {

View on GitHub (pinned to 820761864e)

Solutions

1. Pass --bookie-config /path/to/bookie.conf (and/or --bookiehosts) when running bookie/auto-recovery with the broker
2. Or disable enableRunBookieTogether / enableRunBookieAutoRecoveryTogether in broker.conf and run bookies as separate processes
3. Provide a valid BookKeeper metadata-service configuration in the bookie config file

Example fix

// before
./pulsar broker --run-bookie
// after
./pulsar broker --run-bookie --bookie-config conf/bookie.conf

boolean runBk = args.runBookie || args.runBookieAutoRecovery
    || brokerConf.isEnableRunBookieTogether() || brokerConf.isEnableRunBookieAutoRecoveryTogether();
if (runBk && (args.bookieConfigFile == null || args.bookieConfigFile.isBlank())) {
    throw new IllegalArgumentException("--bookie-config required when running bookie/auto-recovery");
}

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

When it happens

Trigger: Starting 'pulsar broker' with --run-bookie or --run-bookie-auto-recovery (or broker config enabling co-run) but without --bookie-config/-bc.

Common situations: Enabling enableRunBookieAutoRecoveryTogether=true in broker.conf while the deployment script never passes a bookie config; migrating a single-process setup and forgetting the bookie args.

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

• Need to specify a configuration file for broker
• Config file not specified. Please use -c, --config-file or -
• No offloader found for driver '${driverName}'. Please make s
• Could not open configuration file
• Malformed configuration file

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