apache/pulsar · error · IllegalArgumentException

Config file not specified. Please use -c, --config-file or -

Error message

Config file not specified. Please use -c, --config-file or -Dpulsar.config.file to specify the config file.

What it means

PulsarStandaloneStarter boots Pulsar in standalone mode from a broker/service configuration file. Before parsing that file it checks that a config file path was supplied, either via the -c/--config-file command-line option or via the -Dpulsar.config.file system property. If both are empty, it refuses to start with a sensible message instead of failing later with a confusing parse error.

Source

Thrown at pulsar-broker/src/main/java/org/apache/pulsar/PulsarStandaloneStarter.java:61

    private boolean generateDocs = false;
    private Thread shutdownThread;
    @Setter(AccessLevel.PACKAGE)
    private boolean testMode;

    public PulsarStandaloneStarter(String[] args) throws Exception {

        CommandLine commander = new CommandLine(this);

        try {
            commander.parseArgs(args);
            if (this.isHelp()) {
                commander.usage(commander.getOut());
                exit(0);
            }
            if (Strings.isNullOrEmpty(this.getConfigFile())) {
                String configFile = System.getProperty(PULSAR_CONFIG_FILE);
                if (Strings.isNullOrEmpty(configFile)) {
                    throw new IllegalArgumentException(
                            "Config file not specified. Please use -c, --config-file or -Dpulsar.config.file to "
                                    + "specify the config file.");
                }
                this.setConfigFile(configFile);
            }
            if (this.generateDocs) {
                CmdGenerateDocs cmd = new CmdGenerateDocs("pulsar");
                cmd.addCommand("standalone", this);
                cmd.run(null);
                exit(0);
            }

            if (this.isNoBroker() && this.isOnlyBroker()) {
                log.error("Only one option is allowed between '--no-broker' and '--only-broker'");
                commander.usage(commander.getOut());
                return;
            }
        } catch (Exception e) {

View on GitHub (pinned to 820761864e)

Solutions

Pass the config explicitly: `bin/pulsar standalone --config-loader-... ` — for the starter: `java -cp ... org.apache.pulsar.PulsarStandaloneStarter -c conf/standalone.conf` (or `--config-file conf/standalone.conf`).
Or set the system property instead of the flag: `java -Dpulsar.config.file=conf/standalone.conf ...`.
If using bin/pulsar wrapper scripts, ensure arguments are actually forwarded (quoting issues can silently drop -c).
Verify the config file path exists and is readable so the next startup step succeeds.

Example fix

// before
java -jar pulsar.jar standalone

// after
java -Dpulsar.config.file=conf/standalone.conf -jar pulsar.jar standalone
// or: java -jar pulsar.jar standalone -c conf/standalone.conf

Defensive patterns

Strategy: validation

Validate before calling

String configFile = System.getProperty("pulsar.config.file");
if (configFile == null || configFile.isEmpty()) {
    configFile = args.length > 0 && "-c".equals(args[0]) ? args[1] : null;
}
if (configFile == null) {
    throw new IllegalStateException("Pass -c/--config-file or -Dpulsar.config.file before starting standalone");
}
if (!java.nio.file.Files.isRegularFile(java.nio.file.Path.of(configFile))) {
    throw new IllegalStateException("Config file does not exist: " + configFile);
}

Try / catch

try {
    starter.main(args);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Config file not specified")) {
        System.err.println("Start with: -c <path-to-standalone.conf> or -Dpulsar.config.file=<path>");
    }
    throw e;
}

Prevention

Always start via bin/pulsar standalone rather than invoking the starter main class directly so default config handling applies.
In IDE run configurations and Docker CMD/ENTRYPOINT, explicitly include -c conf/standalone.conf.
Verify the JVM property -Dpulsar.config.file is set before -jar/-cp in the command line (order matters).
Check the file exists and is readable from the working directory before launch.

When it happens

Trigger: Starting the standalone service (`bin/pulsar standalone ...` with PulsarStandaloneStarter as main class) without -c/--config-file and without -Dpulsar.config.file=... set in the JVM properties. getConfigFile() returns null/empty and System.getProperty(PULSAR_CONFIG_FILE) ("pulsar.config.file") is also null/empty.

Common situations: Running the standalone jar directly with `java -jar` and forgetting the JVM property; IDE run configurations that omit program arguments; Kubernetes/Docker entrypoints where the -c flag was dropped; upgrading a script that previously relied on an implicit default config.

Related errors

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