{"record":{"id":"991c2543066fbe20","repo":"apache/pulsar","slug":"fieldname-must-not-be-null-or-blank","errorCode":null,"errorMessage":"${fieldName} must not be null or blank","messagePattern":"(.+?) must not be null or blank","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":585,"sourceCode":"        conf.setDescription(description);\n        return this;\n    }\n\n    /** @return the underlying v4 configuration data; for tests in this package only. */\n    ClientConfigurationData getConfForTesting() {\n        return conf;\n    }\n\n    /**\n     * Reject anything that isn't the broker binary protocol. The most common\n     * 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":567,"sourceCodeEnd":600,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-client-v5/src/main/java/org/apache/pulsar/client/impl/v5/PulsarClientBuilderV5.java#L567-L600","documentation":"validatePulsarServiceUrl rejects a null or blank URL at configure time. The v4 client used to fail far downstream with cryptic connection errors when given an empty service URL; the v5 builder fails fast in serviceUrl(String) or connectionPolicy's proxyServiceUrl handling with a message naming the offending field.","triggerScenarios":"Calling builder.serviceUrl(null), serviceUrl(\"\"), serviceUrl(\"   \"), or connectionPolicy with a ConnectionPolicy whose proxyServiceUrl is set to null/blank through the validating path; typically from an environment variable or config key that is unset.","commonSituations":"Missing SERVICE_URL / PULSAR_SERVICE_URL environment variable; properties file key typo so the default null survives; an empty YAML/config value; calling serviceUrl with the result of a lookup that returned Optional.empty-mapped-to-null.","solutions":["Set the service URL explicitly: builder.serviceUrl(\"pulsar://localhost:6650\").","Check where the URL comes from (env var, config file) and fix the missing/blank value before building.","Provide a sensible default for local development and fail with your own message in higher environments.","If proxyServiceUrl is the culprit, either set a valid pulsar:// URL or leave it null in the ConnectionPolicy (null means not configured)."],"exampleFix":"// before\nString url = System.getenv(\"PULSAR_URL\");\nbuilder.serviceUrl(url); // IllegalArgumentException if unset\n// after\nString url = System.getenv(\"PULSAR_URL\");\nObjects.requireNonNull(url, \"PULSAR_URL must be set\");\nbuilder.serviceUrl(url);","handlingStrategy":"validation","validationCode":"String url = envOrConfig(\"serviceUrl\");\nif (url == null || url.isBlank()) {\n    throw new IllegalStateException(\"serviceUrl is not configured (check env/config)\");\n}\nbuilder.serviceUrl(url);","typeGuard":"static boolean isNonBlank(String s) { return s != null && !s.isBlank(); }","tryCatchPattern":"try {\n    builder.serviceUrl(url);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().endsWith(\"must not be null or blank\")) {\n        throw new IllegalStateException(\"Missing serviceUrl configuration\", e);\n    }\n    throw e;\n}","preventionTips":["Fail your own startup fast when the URL env/config key is missing, with a message naming the key.","Give defaults for local dev (pulsar://localhost:6650) but never for production.","Validate all externalized config in one place before constructing clients."],"tags":["pulsar","configuration","service-url","validation"],"backgroundTag":"missing-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"}