{"record":{"id":"6d04eb342d0e6b4f","repo":"apache/pulsar","slug":"need-to-specify-a-configuration-file-for-broker","errorCode":null,"errorMessage":"Need to specify a configuration file for broker","messagePattern":"Need to specify a configuration file for broker","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"pulsar-broker/src/main/java/org/apache/pulsar/PulsarBrokerStarter.java","lineNumber":170,"sourceCode":"        }\n\n        public Integer call() throws Exception {\n            if (starterArguments.help) {\n                commander.usage(commander.getOut());\n                return 0;\n            }\n\n            if (starterArguments.generateDocs) {\n                CmdGenerateDocs cmd = new CmdGenerateDocs(\"pulsar\");\n                cmd.addCommand(\"broker\", commander);\n                cmd.run(null);\n                return 0;\n            }\n\n            // init broker config\n            if (isBlank(starterArguments.brokerConfigFile)) {\n                commander.usage(commander.getOut());\n                throw new IllegalArgumentException(\"Need to specify a configuration file for broker\");\n            } else {\n                final String filepath = Path.of(starterArguments.brokerConfigFile)\n                        .toAbsolutePath().normalize().toString();\n                brokerConfig = loadConfig(filepath);\n            }\n\n            int maxFrameSize = brokerConfig.getMaxMessageSize() + Commands.MESSAGE_SIZE_FRAME_PADDING;\n            if (maxFrameSize >= DirectMemoryUtils.jvmMaxDirectMemory()) {\n                throw new IllegalArgumentException(\"Max message size need smaller than jvm directMemory\");\n            }\n\n            if (!NamespaceBundleSplitAlgorithm.AVAILABLE_ALGORITHMS.containsAll(\n                    brokerConfig.getSupportedNamespaceBundleSplitAlgorithms())) {\n                throw new IllegalArgumentException(\n                        \"The given supported namespace bundle split algorithm has unavailable algorithm. \"\n                                + \"Available algorithms are \" + NamespaceBundleSplitAlgorithm.AVAILABLE_ALGORITHMS);\n            }\n","sourceCodeStart":152,"sourceCodeEnd":188,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-broker/src/main/java/org/apache/pulsar/PulsarBrokerStarter.java#L152-L188","documentation":"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.","triggerScenarios":"Launching the broker process without -c/--broker-config; the argument is present but empty.","commonSituations":"Forgetting --broker-config in systemd/launcher scripts; using a wrapper script that drops empty arguments; running 'pulsar broker' manually without options.","solutions":["Pass the broker config explicitly: --broker-config /path/to/broker.conf (or -c)","Set PULSAR_STANDALONE/launcher script variables so the config path is always supplied","Check the wrapper script/alias to ensure the argument is not dropped when empty"],"exampleFix":"// before\nexec $PULSAR_HOME/bin/pulsar broker\n// after\nexec $PULSAR_HOME/bin/pulsar broker --broker-config $PULSAR_HOME/conf/broker.conf","handlingStrategy":"validation","validationCode":"if (args.length == 0 || Arrays.stream(args)\n        .noneMatch(a -> a.equals(\"-c\") || a.equals(\"--broker-config\"))) {\n    throw new IllegalArgumentException(\"--broker-config is required\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    int rc = starter.call();\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"configuration file for broker\")) {\n        commander.usage(commander.getOut());\n        System.exit(2);\n    }\n    throw e;\n}","preventionTips":["Standardize launch scripts to always include --broker-config $PULSAR_HOME/conf/broker.conf","Fail fast in wrapper scripts when required CLI args are empty"],"tags":["configuration","startup","cli"],"backgroundTag":"missing-required-argument","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}