apache/pulsar · error · IllegalArgumentException

Invalid URL format

Error message

Invalid URL format

What it means

getAbsolutePathFromUrl converts a file URL to an absolute filesystem path. If the URL string cannot be parsed (URISyntaxException thrown when normalizing the URL via new URL(urlString).openConnection().getURL()), it is wrapped as IllegalArgumentException('Invalid URL format').

Source

Thrown at pulsar-client-auth-athenz/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationAthenz.java:310

            ZTSClient.setPrefetchAutoEnable(this.autoPrefetchEnabled);
        }
        return ztsClient;
    }

    private static void checkRequiredParams(Map<String, String> authParams, String... requiredParams) {
        for (String param : requiredParams) {
            checkArgument(isNotBlank(authParams.get(param)), "Missing required parameter: %s", param);
        }
    }

    private static String getAbsolutePathFromUrl(String urlString) {
        try {
            java.net.URL url = new URL(urlString).openConnection().getURL();
            checkArgument("file".equals(url.getProtocol()), "Unsupported protocol: %s", url.getProtocol());
            Path path = Paths.get(url.getPath());
            return path.isAbsolute() ? path.toString() : path.toAbsolutePath().toString();
        } catch (URISyntaxException e) {
            throw new IllegalArgumentException("Invalid URL format", e);
        } catch (InstantiationException | IllegalAccessException | IOException e) {
            throw new IllegalArgumentException("Cannnot get absolute path from specified URL", e);
        }
    }

    private static PrivateKey loadPrivateKey(String privateKeyURL) {
        PrivateKey privateKey = null;
        try {
            URLConnection urlConnection = new URL(privateKeyURL).openConnection();
            String protocol = urlConnection.getURL().getProtocol();
            if ("data".equals(protocol) && !APPLICATION_X_PEM_FILE.equals(urlConnection.getContentType())) {
                throw new IllegalArgumentException(
                        "Unsupported media type or encoding format: " + urlConnection.getContentType());
            }
            String keyData = CharStreams.toString(new InputStreamReader((InputStream) urlConnection.getContent(),
                    Charset.defaultCharset()));
            privateKey = Crypto.loadPrivateKey(keyData);
        } catch (URISyntaxException e) {

View on GitHub (pinned to 820761864e)

Solutions

1. Percent-encode the path and use a proper file URL: 'file:///etc/pulsar/my%20key.pem' (or escape spaces)
2. Verify the URL parses: new URI(value) in a quick check before configuring
3. Prefer a simple absolute path without special characters, or base64-embed the key via the data: URI in 'privateKey'

Example fix

// before
{"privateKeyPath":"file:///etc/pulsar/my key.pem"}
// after
{"privateKeyPath":"file:///etc/pulsar/my%20key.pem"}

try {
    new URI(pathOrUrl).toURL();
} catch (URISyntaxException | MalformedURLException e) {
    throw new IllegalArgumentException("privateKeyPath must be a valid URL, got: " + pathOrUrl, e);
}

boolean isValidUrl(String s) {
    try { new URI(s).toURL(); return true; } catch (Exception e) { return false; }
}

try {
    authentication.configure(authParamsJson);
} catch (IllegalArgumentException e) {
    if (e.getMessage().equals("Invalid URL format")) {
        log.error("privateKeyPath is not a parseable URL; percent-encode spaces and use file:///");
    }
    throw e;
}

When it happens

Trigger: Calling setAuthParams/configure with a privateKeyPath value that is not a syntactically valid URL — e.g. spaces in the path, malformed 'file:/...' syntax, or control characters — so URL construction throws URISyntaxException.

Common situations: Paths with unencoded spaces or non-ASCII characters; Windows paths pasted as 'C:\keys\x.pem' without the file:/// scheme; partially edited config leaving a truncated URL.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

• Invalid privateKey format
• Failed to parse authParams
• Failed to load private key from privateKey or privateKeyPath
• Unsupported media type or encoding format:
• Cannnot get absolute path from specified URL

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/c898416ccece4a9f. Report an issue: GitHub.