apache/pulsar · error · IllegalArgumentException

earlyTokenRefreshPercent must be greater than 0, got: ${valu

Error message

earlyTokenRefreshPercent must be greater than 0, got: ${value}

What it means

parseEarlyRefreshPercent() parses the earlyTokenRefreshPercent config parameter (fraction like 0.2 or integer percent like 20) and rejects values <= 0 with this IllegalArgumentException, which includes the offending value. Like other places, <= 0 is invalid: use a fraction in (0,1) to enable, or >= 1 to disable.

Source

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

     *
     * <p>If the string contains a decimal point it is interpreted as a fractional value in [0, 1]
     * and used directly (e.g. {@code "0.8"} → 0.8). Otherwise the string is treated as an integer
     * percentage and divided by 100 (e.g. {@code "80"} → 0.8, {@code "100"} → 1.0).
     *
     * @param value the raw string from the configuration map
     * @return the resolved fractional percent, must be &gt; 0
     * @throws IllegalArgumentException if the value cannot be parsed or is ≤ 0
     */
    static double parseEarlyRefreshPercent(String value) {
        try {
            double percent;
            if (value.contains(".")) {
                percent = Double.parseDouble(value);
            } else {
                percent = Integer.parseInt(value) / 100.0;
            }
            if (percent <= 0) {
                throw new IllegalArgumentException(
                        CONFIG_PARAM_EARLY_TOKEN_REFRESH_PERCENT + " must be greater than 0, got: " + value);
            }
            return percent;
        } catch (NumberFormatException e) {
            throw new IllegalArgumentException(
                    "Malformed configuration parameter: " + CONFIG_PARAM_EARLY_TOKEN_REFRESH_PERCENT, e);
        }
    }

    @Override
    @Deprecated
    public void configure(Map<String, String> authParams) {
        throw new NotImplementedException("Deprecated; use EncodedAuthenticationParameterSupport");
    }

    @Override
    public void start() throws PulsarClientException {
        flow.initialize();

View on GitHub (pinned to 820761864e)

Solutions

Set the parameter to a positive fraction like 0.2, or an integer percent like 20.
To disable early refresh, use a value >= 1 (e.g. 1 or 100) instead of 0.
Remove the parameter entirely to use the default behavior.

Example fix

// before
{"type":"oauth2","authMethod":"client_secret_post", "earlyTokenRefreshPercent":"0", ...} // throws
// after
{"type":"oauth2","authMethod":"client_secret_post", "earlyTokenRefreshPercent":"0.2", ...}

Defensive patterns

Strategy: validation

Validate before calling

String v = params.optString("earlyTokenRefreshPercent", null);
if (v != null) {
    double d = v.contains(".") ? Double.parseDouble(v) : Integer.parseInt(v) / 100.0;
    if (!(d > 0)) {
        throw new IllegalStateException("earlyTokenRefreshPercent must be > 0, got: " + v);
    }
}
auth.configure(paramsJson);

Try / catch

try {
    auth.configure(paramsJson);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("earlyTokenRefreshPercent")) {
        log.error("Bad earlyTokenRefreshPercent value: {}", e.getMessage());
        params.remove("earlyTokenRefreshPercent"); // retry with default
        auth.configure(params.toString());
        return;
    }
    throw e;
}

Prevention

Use a fraction in (0,1) to enable early refresh; >= 1 disables — never 0.
Strip whitespace and '%' suffixes from config values before writing the JSON.
Omit the key entirely when you want defaults.

When it happens

Trigger: Including "earlyTokenRefreshPercent":"0" (or a negative number) in the OAuth2 auth params JSON passed to configure(); the message interpolates the raw value, e.g. 'earlyTokenRefreshPercent must be greater than 0, got: 0'.

Common situations: Using 0 intending 'disabled' — the correct disable value is >= 1; parsing a decimal-comma locale value ('0,2') failing to parse; whitespace or unit suffixes ('20%') causing a NumberFormatException which surfaces as 'Malformed configuration parameter' instead.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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