{"record":{"id":"bdd193c164041f4a","repo":"apache/pulsar","slug":"fieldname-must-use-the-broker-binary-protocol-bdd193","errorCode":null,"errorMessage":"${fieldName} must use the broker binary protocol (pulsar:// or pulsar+ssl://); got '${url}'.","messagePattern":"(.+?) must use the broker binary protocol \\(pulsar:// or pulsar\\+ssl://\\); got '(.+?)'\\.","errorType":"exception","errorClass":"java.lang.IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"pulsar-client-v5/src/main/java/org/apache/pulsar/client/impl/v5/PulsarClientBuilderV5.java","lineNumber":596,"sourceCode":"     * mistake is passing the admin/web service URL ({@code http://...}) where a\n     * broker URL is expected — call that out specifically. The v4 client used to\n     * silently fail far downstream with cryptic connection errors; here we fail\n     * fast at configure time with a message the user can act on.\n     */\n    private static void validatePulsarServiceUrl(String url, String fieldName) {\n        if (url == null || url.isBlank()) {\n            throw new IllegalArgumentException(fieldName + \" must not be null or blank\");\n        }\n        if (url.startsWith(\"pulsar://\") || url.startsWith(\"pulsar+ssl://\")) {\n            return;\n        }\n        if (url.startsWith(\"http://\") || url.startsWith(\"https://\")) {\n            throw new IllegalArgumentException(fieldName + \" must use the broker binary protocol \"\n                    + \"(pulsar:// or pulsar+ssl://); got '\" + url + \"'. This looks like the admin/web \"\n                    + \"service URL — pass the broker service URL instead (typically port 6650, or \"\n                    + \"6651 for TLS).\");\n        }\n        throw new IllegalArgumentException(fieldName + \" must use the broker binary protocol \"\n                + \"(pulsar:// or pulsar+ssl://); got '\" + url + \"'.\");\n    }\n}\n","sourceCodeStart":578,"sourceCodeEnd":600,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-client-v5/src/main/java/org/apache/pulsar/client/impl/v5/PulsarClientBuilderV5.java#L578-L600","documentation":"Thrown by validatePulsarServiceUrl in PulsarClientBuilderV5 when the service URL set on the client builder does not use the broker's binary protocol scheme (pulsar:// or pulsar+ssl://). The Pulsar client connects to brokers over a binary TCP protocol; HTTP(S) URLs belong to the admin/web service, so passing one means the client would have no way to speak to the broker. The library rejects it eagerly at builder configuration time rather than failing later with an opaque connection error.","triggerScenarios":"Calling serviceUrl(...) (or a connectionPolicy that derives the URL) on PulsarClientBuilderV5 with a URL whose scheme is not pulsar:// or pulsar+ssl:// — e.g. http:// or https://, an empty scheme, or a typo like pulsar//. When an http(s) URL is passed, the message additionally hints it looks like the admin/web service URL.","commonSituations":"Copy-pasting the admin URL (http://broker:8080, typically from a Kubernetes service or the standalone broker's webServicePort) instead of the broker service URL; confusing port 8080 (HTTP admin) with port 6650 (binary broker) or 6651 (TLS broker); building the URL from environment variables that only carry the HTTP endpoint.","solutions":["Replace the URL with the broker binary service URL, typically pulsar://<host>:6650 or pulsar+ssl://<host>:6651","If you only have the admin URL, derive the broker URL: same host, scheme pulsar:// (or pulsar+ssl:// for TLS), port 6650 (or 6651 for TLS)","Check your environment/config variables for the right value — many deployments expose both PULSAR_WEB_SERVICE_URL (http) and PULSAR_BROKER_SERVICE_URL (pulsar)"],"exampleFix":"// before\nPulsarClient.builder().serviceUrl(\"http://localhost:8080\");\n// after\nPulsarClient.builder().serviceUrl(\"pulsar://localhost:6650\");","handlingStrategy":"validation","validationCode":"boolean isValidBrokerUrl(String url) {\n    return url != null && (url.startsWith(\"pulsar://\") || url.startsWith(\"pulsar+ssl://\"));\n}\nif (!isValidBrokerUrl(cfg.brokerUrl)) throw new IllegalArgumentException(\"Use pulsar://host:6650 or pulsar+ssl://host:6651, not an http(s) admin URL\");","typeGuard":"boolean isBrokerServiceUrl(String url) {\n    return url != null && url.startsWith(\"pulsar://\") || (url != null && url.startsWith(\"pulsar+ssl://\"));\n}","tryCatchPattern":"try {\n    builder.serviceUrl(url);\n} catch (IllegalArgumentException e) {\n    log.error(\"Bad service URL: {}\", e.getMessage());\n}","preventionTips":["Keep admin (http://host:8080) and broker (pulsar://host:6650) URLs in separate config keys","Default to port 6650 (plain) or 6651 (TLS) when constructing broker URLs","Validate the scheme before handing any URL to the client builder"],"tags":["configuration","url","client-builder","validation"],"backgroundTag":"invalid-service-url","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"}