apache/pulsar · error · IllegalArgumentException

Required configuration parameter: ${name}

Error message

Required configuration parameter: ${name}

What it means

FlowBase.parseParameterString extracts a required auth parameter by name and throws IllegalArgumentException('Required configuration parameter: <name>') if the value is missing or empty. It enforces mandatory OAuth2 configuration such as issuerUrl and privateKey before the client starts.

Source

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

    }

    public void initialize() throws PulsarClientException {
        try {
            this.metadata = createMetadataResolver().resolve();
        } catch (IOException e) {
            log.error().exception(e).log("Unable to retrieve OAuth 2.0 server metadata");
            throw new PulsarClientException.AuthenticationException("Unable to retrieve OAuth 2.0 server metadata");
        }
    }

    protected MetadataResolver createMetadataResolver() {
        return DefaultMetadataResolver.fromIssuerUrl(issuerUrl, getHttpClient(), wellKnownMetadataPath);
    }

    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);

View on GitHub (pinned to 820761864e)

Solutions

1. Provide all required params: issuerUrl, privateKey (and audience if required by the IdP)
2. Check the config source actually loads the key (env var, secret mount)
3. Add a startup validation step printing which params are present

Example fix

// before
Map<String, String> params = new HashMap<>(); // missing issuerUrl
auth.configure(...);
// after
Map<String, String> params = new HashMap<>();
params.put("issuerUrl", "https://auth.example.com");
params.put("privateKey", "file:///etc/pulsar/auth/key.json");

Map<String, String> required = Map.of("issuerUrl", issuerUrl, "privateKey", privateKey);
for (var e : required.entrySet()) {
    if (e.getValue() == null || e.getValue().isBlank()) {
        throw new IllegalStateException("Required configuration parameter missing: " + e.getKey());
    }
}

boolean hasNonBlank(java.util.Map<String,String> params, String name) {
    String v = params.get(name);
    return v != null && !v.isBlank();
}

try {
    flow.initialize();
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Required configuration parameter")) {
        throw new ConfigException("Provide all required OAuth2 params (issuerUrl, privateKey): " + e.getMessage());
    }
    throw e;
}

When it happens

Trigger: Building AuthenticationOAuth2 without issuerUrl or privateKey in the auth parameter map; passing a null/empty string value; parameters dropped by config-loading code that filters empty values.

Common situations: Environment variable for the parameter not set so interpolation yields empty; missing key in YAML; constructor path that bypasses defaults and requires explicit params.

Related errors

• Malformed configuration parameter: earlyTokenRefreshPercent
• Unsupported media type or encoding format: ${contentType}
• Invalid privateKey format
• Unable to read private key: ${message}
• Bookie 'group' parameters is missing

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