{"record":{"id":"22d3eaf3699ea7c5","repo":"apache/pulsar","slug":"webserviceport-webserviceporttls-or-http-https-bin","errorCode":null,"errorMessage":"webServicePort/webServicePortTls or http/https bindAddresses must be present","messagePattern":"webServicePort/webServicePortTls or http/https bindAddresses must be present","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"pulsar-broker/src/main/java/org/apache/pulsar/broker/PulsarService.java","lineNumber":877,"sourceCode":"                .attr(\"gitRevision\", PulsarVersion.getGitSha())\n                .attr(\"gitBranch\", PulsarVersion.getGitBranch())\n                .attr(\"buildUser\", PulsarVersion.getBuildUser())\n                .attr(\"buildHost\", PulsarVersion.getBuildHost())\n                .attr(\"buildTime\", PulsarVersion.getBuildTime())\n                .log(\"Starting Pulsar Broker service\");\n\n        long startTimestamp = System.currentTimeMillis();  // start time mills\n\n        mutex.lock();\n        try {\n            if (state != State.Init) {\n                throw new PulsarServerException(\"Cannot start the service once it was stopped\");\n            }\n\n            if (config.getWebServicePort().isEmpty()\n                    && config.getWebServicePortTls().isEmpty()\n                    && BindAddressValidator.validateBindAddresses(config, Arrays.asList(\"http\", \"https\")).isEmpty()) {\n                throw new IllegalArgumentException(\n                        \"webServicePort/webServicePortTls or http/https bindAddresses must be present\");\n            }\n\n            if (config.isAuthorizationEnabled() && !config.isAuthenticationEnabled()) {\n                throw new IllegalStateException(\"Invalid broker configuration. Authentication must be enabled with \"\n                        + \"authenticationEnabled=true when authorization is enabled with authorizationEnabled=true.\");\n            }\n\n            if (config.getDefaultRetentionSizeInMB() > 0\n                    && config.getBacklogQuotaDefaultLimitBytes() > 0\n                    && config.getBacklogQuotaDefaultLimitBytes()\n                    >= (config.getDefaultRetentionSizeInMB() * 1024L * 1024L)) {\n                throw new IllegalArgumentException(String.format(\"The retention size must > the backlog quota limit \"\n                                + \"size, but the configured backlog quota limit bytes is %d, the retention size is %d\",\n                        config.getBacklogQuotaDefaultLimitBytes(),\n                        config.getDefaultRetentionSizeInMB() * 1024L * 1024L));\n            }\n","sourceCodeStart":859,"sourceCodeEnd":895,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-broker/src/main/java/org/apache/pulsar/broker/PulsarService.java#L859-L895","documentation":"During PulsarService.start(), the broker validates that an HTTP(S) web service endpoint can be bound. It requires at least one of: a non-empty webServicePort, a non-empty webServicePortTls, or at least one http/https entry among bindAddresses. If all are empty/unset, IllegalArgumentException is thrown because the broker's web service would have nowhere to listen.","triggerScenarios":"Starting a broker with a ServiceConfiguration where config.getWebServicePort().isEmpty() && config.getWebServicePortTls().isEmpty() && BindAddressValidator.validateBindAddresses(config, [\"http\",\"https\"]).isEmpty() — i.e. webServicePort and webServicePortTls left unset (or 0/empty) and no bindAddresses entries of type http or https configured.","commonSituations":"Hand-edited broker.conf / standalone.conf where ports were deleted or set to empty; copying a config that only sets tls ports but disabling TLS elsewhere; Docker/K8s env-substitution producing empty values (e.g. webServicePort=${PORT} with PORT unset); misusing bindAddresses without an http/https entry (only pulsar/https entries).","solutions":["Set webServicePort=8080 (and/or webServicePortTls=8443) in your broker config file or via environment/property override.","Alternatively configure bindAddresses with an http (or https) entry, e.g. bindAddresses=http://0.0.0.0:8080, matching BindAddressValidator's accepted scheme.","Check env var substitution: in containerized setups ensure the variable feeding webServicePort is actually set and non-empty.","Run with --help/config docs to confirm the exact key names for your version (older versions used numeric 0 as 'unset')."],"exampleFix":"// before (broker.conf)\nwebServicePort=\nwebServicePortTls=\n\n// after\nwebServicePort=8080\nwebServicePortTls=8443","handlingStrategy":"validation","validationCode":"ServiceConfiguration cfg = new ServiceConfiguration();\nPropertyUtils.loadProperties(cfg, props, /* includeHidden */ false);\nboolean hasPort = cfg.getWebServicePort().isPresent() || cfg.getWebServicePortTls().isPresent();\nboolean hasBindAddress = props.stringPropertyNames().stream()\n        .anyMatch(k -> k.startsWith(\"bindAddresses=\") || false)\n        || props.getProperty(\"bindAddresses\", \"\").matches(\".*(http|https)://.*\");\nif (!hasPort && !hasBindAddress) {\n    throw new IllegalArgumentException(\"Set webServicePort/webServicePortTls or an http/https bindAddress\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    pulsarService.start();\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"webServicePort/webServicePortTls\")) {\n        System.err.println(\"Broker config is missing an HTTP(S) listener: set webServicePort=8080 or a bindAddress\");\n    }\n    throw e;\n}","preventionTips":["Never leave both webServicePort and webServicePortTls blank; comment them out only if you add a bindAddress.","In containers, assert required env vars (feeding webServicePort) are non-empty before startup.","Validate configs with a pre-flight check or `pulsar broker --help`-style dry validation before deploying.","When using bindAddresses, ensure at least one entry uses the http or https scheme."],"tags":["configuration","broker","web-service","ports","startup"],"backgroundTag":"missing-required-config-property","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}