{"record":{"id":"0a415dc6d0c039e8","repo":"apache/pulsar","slug":"malformed-configuration-parameter-name","errorCode":null,"errorMessage":"Malformed configuration parameter: ${name}","messagePattern":"Malformed configuration parameter: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth/oauth2/FlowBase.java","lineNumber":275,"sourceCode":"    }\n\n    static String parseParameterString(Map<String, String> params, String name) {\n        String s = params.get(name);\n        if (StringUtils.isEmpty(s)) {\n            throw new IllegalArgumentException(\"Required configuration parameter: \" + name);\n        }\n        return s;\n    }\n\n    static URL parseParameterUrl(Map<String, String> params, String name) {\n        String s = params.get(name);\n        if (StringUtils.isEmpty(s)) {\n            throw new IllegalArgumentException(\"Required configuration parameter: \" + name);\n        }\n        try {\n            return new URL(s);\n        } catch (MalformedURLException e) {\n            throw new IllegalArgumentException(\"Malformed configuration parameter: \" + name);\n        }\n    }\n\n    static Duration parseParameterDuration(Map<String, String> params, String name) {\n        String value = params.get(name);\n        if (StringUtils.isNotBlank(value)) {\n            try {\n                return Duration.parse(value);\n            } catch (DateTimeParseException e) {\n                throw new IllegalArgumentException(\"Malformed configuration parameter: \" + name, e);\n            }\n        }\n        return null;\n    }\n\n    @Override\n    // Synchronized to pair with the synchronized getHttpClient()/resolveHttpClientFactory() lazy init:\n    // otherwise a close() racing the first fetch reads pulsarHttpClient/standaloneHttpClientFactory without the","sourceCodeStart":257,"sourceCodeEnd":293,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth/oauth2/FlowBase.java#L257-L293","documentation":"FlowBase.parseParameterUrl converts a named configuration parameter into a java.net.URL. If the value is non-empty but not a syntactically valid URL, `new URL(s)` throws MalformedURLException and this IllegalArgumentException is thrown naming the offending parameter. It signals a client configuration problem, not a runtime network failure.","triggerScenarios":"Calling AuthenticationFactoryOAuth2.clientCredentials(...) or refreshToken(...) (or FlowBuilder) with a non-URL value for issuerUrl or clientCredentialsUrl: missing scheme ('localhost:8443' instead of 'https://localhost:8443'), typos like 'htp://', stray spaces, or an invalid path.","commonSituations":"Copy-pasting issuer URLs from docs without the https:// scheme; failed env-var interpolation leaving placeholders; quoting issues in YAML/properties files; passing a file path where a URL is expected.","solutions":["Fix the named parameter's value so it is an absolute, well-formed URL including scheme (e.g. https://accounts.google.com).","Check the resolved config source (env var, YAML, properties) actually contains the expected string.","Strip surrounding quotes, whitespace, and newlines from the value."],"exampleFix":"// before\nString issuerUrl = System.getenv(\"ISSUER\"); // \"localhost:8080\"\nAuthenticationFactoryOAuth2.clientCredentials(new URL(issuerUrl), credFile, \"audience\"); // throws\n// after\nString issuerUrl = System.getenv(\"ISSUER\"); // \"https://localhost:8080\"\nAuthenticationFactoryOAuth2.clientCredentials(new URL(issuerUrl), credFile, \"audience\");","handlingStrategy":"validation","validationCode":"static URL requireUrl(String name, String s) {\n    if (s == null || s.trim().isEmpty()) throw new IllegalArgumentException(\"Missing \" + name);\n    try { return new java.net.URL(s); }\n    catch (java.net.MalformedURLException e) { throw new IllegalArgumentException(name + \" is not a valid URL: \" + s, e); }\n}","typeGuard":"boolean isValidUrl(String s) {\n    if (s == null) return false;\n    try { new java.net.URL(s); return true; } catch (java.net.MalformedURLException e) { return false; }\n}","tryCatchPattern":"try {\n    client = AuthenticationFactoryOAuth2.clientCredentials(issuerUrl, credFile, audience);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().startsWith(\"Malformed configuration parameter\")) {\n        throw new ConfigException(\"OAuth2 URL config invalid: \" + e.getMessage(), e);\n    }\n    throw e;\n}","preventionTips":["Always include the scheme (https://) in issuerUrl and clientCredentialsUrl values.","Parse all URL-typed parameters yourself at config-load time to fail fast.","Validate resolved env vars/properties before constructing the Authentication object.","Keep values free of surrounding quotes, whitespace, and stray trailing characters."],"tags":["oauth2","configuration","url","pulsar-client"],"backgroundTag":"malformed-url-config","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"}