apache/pulsar · error · IllegalArgumentException

Invalid key format

Error message

Invalid key format

What it means

loadKey() parses the given key URL, and a URISyntaxException means the string is not a valid URI at all (illegal characters, spaces, malformed scheme). The reader converts this into a clearer IllegalArgumentException('Invalid key format') so callers get an actionable message instead of a raw URI exception.

Source

Thrown at pulsar-client/src/main/java/org/apache/pulsar/client/impl/DefaultCryptoKeyReader.java:104

        return keyInfo;
    }

    private byte[] loadKey(String keyUrl) throws IOException, IllegalAccessException, InstantiationException {
        try {
            URLConnection urlConnection = new URL(keyUrl).openConnection();
            try {
                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());
                }
                return IOUtils.toByteArray(urlConnection);
            } finally {
                IOUtils.close(urlConnection);
            }
        } catch (URISyntaxException e) {
            throw new IllegalArgumentException("Invalid key format");
        }
    }

}

View on GitHub (pinned to 820761864e)

Solutions

1. URL-encode the key URL (URLEncoder.encode for components or URI-based escaping) before passing it.
2. Fix the key URL string: replace spaces and illegal characters with percent-encoded equivalents.
3. If referencing a local file, use a properly encoded file:///abs/path URI or the file-path constructor variant.

Example fix

// before
new DefaultCryptoKeyReader("file:///keys/my key.pem", "file:///keys/priv.pem");
// after
new DefaultCryptoKeyReader("file:///keys/my%20key.pem", "file:///keys/priv.pem");

try { new URI(keyUrl); } catch (URISyntaxException e) {
  throw new IllegalArgumentException("Malformed key URL: " + keyUrl, e);
}

try {
  reader.getPrivateKey(keyName);
} catch (IllegalArgumentException e) {
  // invalid key format: URL-encode and retry
}

When it happens

Trigger: Passing a malformed key URL string to DefaultCryptoKeyReader (constructor with keyReader public/private key URLs) that getPublicKey/getPrivateKey then try to load — e.g. a path with spaces or unescaped special characters like '{' '}' '|'.

Common situations: Pasting file paths with spaces without encoding; template placeholders like ${KEY_URL} never substituted; keys built by string concatenation without URI encoding.

Related errors

• the value ${strUri} in the `advertisedListeners` configure i
• Unsupported media type or encoding format: ${contentType}
• Broker doesn't allow forced deletion of namespaces
• Local cluster is not part of replicate cluster list
• Entry filter '${filterName}' not found

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