apache/pulsar · error · IllegalArgumentException

Malformed configuration file

Error message

Malformed configuration file

What it means

readBookieConfFile catches ConfigurationException from bookieConf.loadConf/bookieConf.validate and rethrows it as 'Malformed configuration file'. It means the Bookie configuration file exists but cannot be parsed or fails validation by the configuration framework.

Source

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

        @Option(names = {"-h", "--help"}, usageHelp = true, description = "Show this help message")
        private boolean help = false;

        @Option(names = {"-g", "--generate-docs"}, description = "Generate docs")
        private boolean generateDocs = false;
    }

    private static ServerConfiguration readBookieConfFile(String bookieConfigFile) throws IllegalArgumentException {
        ServerConfiguration bookieConf = new ServerConfiguration();
        try {
            bookieConf.loadConf(new File(bookieConfigFile).toURI().toURL());
            bookieConf.validate();
            log.info().attr("file", bookieConfigFile).log("Using bookie configuration file");
        } catch (MalformedURLException e) {
            log.error().attr("file", bookieConfigFile).exception(e).log("Could not open configuration file");
            throw new IllegalArgumentException("Could not open configuration file");
        } catch (ConfigurationException e) {
            log.error().attr("file", bookieConfigFile).exception(e).log("Malformed configuration file");
            throw new IllegalArgumentException("Malformed configuration file");
        }

        if (bookieConf.getMaxPendingReadRequestPerThread() < bookieConf.getRereplicationEntryBatchSize()) {
            throw new IllegalArgumentException(
                "rereplicationEntryBatchSize should be smaller than " + "maxPendingReadRequestPerThread");
        }
        return bookieConf;
    }

    protected static class BrokerStarter implements Callable<Integer> {
        private ServiceConfiguration brokerConfig;
        private PulsarService pulsarService;
        private LifecycleComponent bookieServer;
        private volatile CompletableFuture<Void> bookieStartFuture;
        private AutoRecoveryMain autoRecoveryMain;
        private StatsProvider bookieStatsProvider;
        private ServerConfiguration bookieConfig;
        private WorkerService functionsWorkerService;

View on GitHub (pinned to 820761864e)

Solutions

1. Fix the syntax/values in the bookie configuration file; compare against conf/bookie.conf shipped with your Pulsar version
2. Check the logged ConfigurationException (stack trace shows the offending property)
3. Validate types of numeric/boolean properties and remove unsupported keys from old versions

Example fix

// before (bookie.conf)
bookiePort=not-a-number
// after
bookiePort=3181

// Pre-parse check in the caller
Properties props = new Properties();
try (InputStream in = Files.newInputStream(Path.of(bookieConfigFile))) {
    props.load(in);
    if (!props.stringPropertyNames().contains("bookiePort")) {
        throw new IllegalStateException("bookie.conf missing required keys");
    }
}

try {
    BookKeeperConfiguration conf = readBookieConfFile(bookieConfigFile);
} catch (IllegalArgumentException e) {
    if (e.getMessage().equals("Malformed configuration file")) {
        throw new IllegalStateException("Invalid bookie.conf " + bookieConfigFile + ": fix syntax/types", e);
    }
    throw e;
}

When it happens

Trigger: Bookie config file contains invalid syntax, wrong value types (e.g. non-numeric port), or a value that fails BookKeeper's Configuration validate() step; thrown when --bookie-config points to a parseable-path but invalid-content file.

Common situations: Hand-edited bookie.conf with typos; copying an incompatible bookkeeper config across versions; missing required properties; wrong encoding or stray characters in the file.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• No offloader found for driver '${driverName}'. Please make s
• Could not open configuration file
• Need to specify a configuration file for broker
• Max message size need smaller than jvm directMemory
• The given supported namespace bundle split algorithm has una

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