apache/pulsar · error · IllegalArgumentException

Malformed configuration parameter: ${name}

Error message

Malformed configuration parameter: ${name}

What it means

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.

Source

Thrown at pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth/oauth2/FlowBase.java:275

    }

    static String parseParameterString(Map<String, String> params, String name) {
        String s = params.get(name);
        if (StringUtils.isEmpty(s)) {
            throw new IllegalArgumentException("Required configuration parameter: " + name);
        }
        return s;
    }

    static URL parseParameterUrl(Map<String, String> params, String name) {
        String s = params.get(name);
        if (StringUtils.isEmpty(s)) {
            throw new IllegalArgumentException("Required configuration parameter: " + name);
        }
        try {
            return new URL(s);
        } catch (MalformedURLException e) {
            throw new IllegalArgumentException("Malformed configuration parameter: " + name);
        }
    }

    static Duration parseParameterDuration(Map<String, String> params, String name) {
        String value = params.get(name);
        if (StringUtils.isNotBlank(value)) {
            try {
                return Duration.parse(value);
            } catch (DateTimeParseException e) {
                throw new IllegalArgumentException("Malformed configuration parameter: " + name, e);
            }
        }
        return null;
    }

    @Override
    // Synchronized to pair with the synchronized getHttpClient()/resolveHttpClientFactory() lazy init:
    // otherwise a close() racing the first fetch reads pulsarHttpClient/standaloneHttpClientFactory without the

View on GitHub (pinned to 820761864e)

Solutions

1. Fix the named parameter's value so it is an absolute, well-formed URL including scheme (e.g. https://accounts.google.com).
2. Check the resolved config source (env var, YAML, properties) actually contains the expected string.
3. Strip surrounding quotes, whitespace, and newlines from the value.

Example fix

// before
String issuerUrl = System.getenv("ISSUER"); // "localhost:8080"
AuthenticationFactoryOAuth2.clientCredentials(new URL(issuerUrl), credFile, "audience"); // throws
// after
String issuerUrl = System.getenv("ISSUER"); // "https://localhost:8080"
AuthenticationFactoryOAuth2.clientCredentials(new URL(issuerUrl), credFile, "audience");

static URL requireUrl(String name, String s) {
    if (s == null || s.trim().isEmpty()) throw new IllegalArgumentException("Missing " + name);
    try { return new java.net.URL(s); }
    catch (java.net.MalformedURLException e) { throw new IllegalArgumentException(name + " is not a valid URL: " + s, e); }
}

boolean isValidUrl(String s) {
    if (s == null) return false;
    try { new java.net.URL(s); return true; } catch (java.net.MalformedURLException e) { return false; }
}

try {
    client = AuthenticationFactoryOAuth2.clientCredentials(issuerUrl, credFile, audience);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Malformed configuration parameter")) {
        throw new ConfigException("OAuth2 URL config invalid: " + e.getMessage(), e);
    }
    throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• earlyTokenRefreshPercent must be greater than 0.
• Required configuration parameters: tlsCertFile, tlsKeyFile
• Unsupported auth method: ${tokenEndpointAuthMethod}
• EarlyTokenRefreshPercent must be greater than 0.
• Unsupported auth method: ${authMethod}

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