{"record":{"id":"350195a82c6fa33e","repo":"apache/pulsar","slug":"invalid-privatekey-format","errorCode":null,"errorMessage":"Invalid privateKey format","messagePattern":"Invalid privateKey format","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth/oauth2/ClientCredentialsFlow.java","lineNumber":146,"sourceCode":"            URLConnection urlConnection = new org.apache.pulsar.client.api.url.URL(privateKeyURL).openConnection();\n            try {\n                String protocol = urlConnection.getURL().getProtocol();\n                String contentType = urlConnection.getContentType();\n                if (\"data\".equals(protocol) && !\"application/json\".equals(contentType)) {\n                    throw new IllegalArgumentException(\n                            \"Unsupported media type or encoding format: \" + urlConnection.getContentType());\n                }\n                KeyFile privateKey;\n                try (Reader r = new InputStreamReader((InputStream) urlConnection.getContent(),\n                        StandardCharsets.UTF_8)) {\n                    privateKey = KeyFile.fromJson(r);\n                }\n                return privateKey;\n            } finally {\n                IOUtils.close(urlConnection);\n            }\n        } catch (URISyntaxException | InstantiationException | IllegalAccessException e) {\n            throw new IOException(\"Invalid privateKey format\", e);\n        }\n    }\n\n    @Override\n    public void initialize() throws PulsarClientException {\n        super.initialize();\n        assert this.metadata != null;\n\n        URL tokenUrl = this.metadata.getTokenEndpoint();\n        this.exchanger = new TokenClient(tokenUrl, getHttpClient());\n        initialized = true;\n    }\n\n    public TokenResult authenticate() throws PulsarClientException {\n        // read the private key from storage\n        KeyFile keyFile;\n        try {\n            keyFile = loadPrivateKey(this.privateKey);","sourceCodeStart":128,"sourceCodeEnd":164,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth/oauth2/ClientCredentialsFlow.java#L128-L164","documentation":"loadPrivateKey() wraps URISyntaxException, InstantiationException and IllegalAccessException into IOException('Invalid privateKey format'). This means the privateKey value could not be interpreted as a valid URL at all — typically a malformed URI syntax in the privateKey parameter (not the JSON payload itself, which is handled elsewhere).","triggerScenarios":"privateKey string containing spaces, unencoded special characters, or an invalid scheme so new URL(privateKeyURL) throws URISyntaxException; file paths with illegal characters; a value like 'file:/path with spaces/key.json'.","commonSituations":"Paste errors adding whitespace/newlines to the privateKey config; paths with non-URL-safe characters; using a plain path string instead of a proper file: URL.","solutions":["URL-encode special characters in the privateKey value (spaces as %20)","Prefix local paths with file: and ensure valid URI syntax","Log/print the privateKey value (careful with secrets) and test it with new URI(value) first"],"exampleFix":"// before\nString key = \"/etc/pulsar/oauth2/my key.json\";\n// after\nString key = \"file:/etc/pulsar/oauth2/my%20key.json\";","handlingStrategy":"validation","validationCode":"String key = authParams.get(\"privateKey\");\ntry {\n    new java.net.URI(key);\n} catch (java.net.URISyntaxException e) {\n    throw new IllegalArgumentException(\"privateKey is not a valid URI: \" + e.getMessage());\n}","typeGuard":"boolean isValidKeyUri(String v) {\n    if (v == null || v.isBlank()) return false;\n    try { new java.net.URI(v); return true; } catch (java.net.URISyntaxException e) { return false; }\n}","tryCatchPattern":"try {\n    flow.initialize();\n} catch (PulsarClientException.AuthenticationException e) {\n    if (e.getMessage().contains(\"Invalid privateKey format\")) {\n        throw new ConfigException(\"privateKey must be a well-formed URI (URL-encode spaces/special chars)\", e);\n    }\n    throw e;\n}","preventionTips":["URL-encode paths containing spaces or special characters","Prefix local file paths with file: scheme","Validate the privateKey URI with new URI(value) before configuring the client"],"tags":["oauth2","config","url"],"backgroundTag":"invalid-private-key-format","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"}